Last modified January 05, 2012
Sorting
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 dot-notated property to perform the sort on for the data object. Some endpoints allow for shortened versions of property names for those that are commonly queried against, such as name and state under the places endpoint, instead of having to provide the full dot-notation format. Refer to the documentation for each endpoint for information regarding which short names are supported. |
| 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. |
Chaining Sort Queries
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.
Sorting Differences with Closest and Within Actions
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.