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=10Another use-case would be to obtain the observation with the maximum temperature within the United States:
/observations/search?query=country:us&sort=temp:-1Or the observation with the lowest current temperature with-in the state of Minnesota:
/observations/search?query=state:mn,temp:-999&sort=tempNote 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.
Using sort
The following are supported formats for using sort:
# Query using a single value and optional operator
/{endpoint}/{action}?sort={property}
# Query using a range of values
/{endpoint}/{action}?sort={property}:{direction}| Option | Description | Default |
|---|---|---|
property | Type: string (required)The property to perform the sort on for the data object. Endpoints allow for shortened versions of property names, such as name and state under the /places endpoint, instead of having to provide the dot-notation format. Refer to the documentation for each endpoint for information for information regarding which properties may be used for sorting. | |
direction | Type: 0, 1, or -1 (optional)Controls the direction of a sort when provided. 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 direction 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=500Note 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.
For example, the following request will return 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:-1The 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:-1While the difference in the request is minor, each has their specific uses and will usually return completely different results.