The sort parameter allows making requests for data that is sorted by one or more elements from the data set. This feature allows fetching results presorted for easier processing and, when combined with the query parameter, can obtain specific results that would normally not be readily available from a normal endpoint action.
One use-case for the sort parameter would be to sort locations by population. For example, the following query will return the 10 cities with the highest population within a 50 mile radius of Minneapolis, MN, descending by population:
/places/within?p=minneapolis,mn&radius=50miles&sort=pop:-1&limit=10
Another use-case would be to obtain the observation with the maximum temperature within the United States:
/observations/search?query=country:us&sort=temp:-1
Or the observation with the lowest current temperature with-in the state of Minnesota:
/observations/search?query=state:mn,temp:-999&sort=temp
Note in this example we included a stringed query to ensure we only included observations with a temperature greater than -999. This is a simple way to skip observations that did not include a temperature.
The following is the basic format for using sort:
/ACTION?sort=PROP
/ACTION?sort=PROP:SORT_DIR
| PROP | The property to perform the sort on for the data object. Endpoints allow for specific property names for those that are commonly used for sorting, such as name and state under the places endpoint. Refer to the documentation for each endpoint for information regarding which properties may be used for sorting. |
| SORT_DIR | When provided this controls the direction of a sort. For ascending, set to 1, descending set to -1. To disable all sorting for a property, set to 0. Disabling the sort functionality is useful to override predefined sorting in an endpoint. If the SORT_DIR is not provided, then sorting will be ascending by default. |
Multiple properties can be chained together in a single request to perform more complex sort queries. Sort queries should be separated by commas, and the sorting will occur in the order of the specified properties.
For example, the following observations request will return observations within the United States, sorted first by state ascending and then by temperature descending:
/observations/search?query=country:us&sort=state,temp:-1&limit=500
Note that the individual endpoint and/or subscription level may limit the maximum number of results that may be returned in a single query.
When using the sort parameter with the closest action, beware that distance will take priority over the sort parameter. Whereas, using the sort parameter in conjunction of the within action, distance is ignored so only the sort parameter is used. This difference can be seen via the following queries:
The following will fetch the ten closest observations to Minneapolis then sort the results descending based on temperature:
/observations/closest?p=minneapolis,mn&radius=50miles&limit=10&sort=temp:-1
The following will fetch the ten warmest observations within a 50 mile radius of Minneapolis, MN and sort the results descending based on temperature:
/observations/within?p=minneapolis,mn&radius=50miles&limit=10&sort=temp:-1
While the difference in the request is minor, each has their specific uses and will usually return completely different results.
Last modified: July 30, 2020