change to OSCAR/Surface API in next release (pagination)

change to OSCAR/Surface API in next release (pagination)

de Timo Proescholdt -
Número de respuestas: 0

Dear WIGOS and OSCAR community,

we would like to inform you that there will be a change to the REST API in OSCAR/Surface in the next release, scheduled for September 2021.

The search endpoint (https://oscar.wmo.int/surface/rest/api/search/station) will implement pagination. This means that the search result returned by the endpoint will have a maximum set of stations (set to 50000 by default). If the total result size exceeds this threshold, additional pages need to be fetched and the result combined.

The concrete changes to the endpoint are:

- the result (list of stations) will be contained in a JSON structure under the key "stationSearchResults" instead of being returned directly.
- the JSON structure returns additional information about the result in the keys "totalCount", "pageCount", "pageNumber" and "itemsPerPage", giving information about the total number of search results, the total number of pages, the current page number and the maximum number of results per page.
- the endpoint accepts additional parameters "page" and "items", to indicate which page of the result set should be fetched and how many items of the result set should be in each page. The "page" defaults to 1 and needs to be greater than 0, while the items defaults to 50000 and needs to be smaller or equal to 50000.

Please find a jupyter notebook with  some demo code in python for your convenience of how pagination in the search API can be implemented.

with kind regards,
Timo