Query Options
When you use the Query API, you can specify query options that define what data is returned and how it is formatted. Query options are specified as URL parameters. The query options used by the Query API include a subset of the query options defined by an Open Data Protocol (OData) specification. In addition to the OData query options, the Query API also provides custom query options, such as a spatial filter. Use spatial filter to define the area to query.
OData Query Options
| Query Option | Description |
|---|---|
| $filter | Specifies a conditional expression for a list of properties and values. Note: You cannot filter on the latitude and longitude entity properties. The Query API supports logical operators and precedence grouping. For a complete list of the supported operators, see the Supported $filter Operators section below. The Query API also supports the StartsWith and EndsWith functions to perform wildcard searches. Only one wildcard search can be performed at a time, and wildcard searches cannot be combined with additional $filter expressions. Wildcard searches are not supported for the PointsOfInterest data source. For more information, see The Wildcard Search Functions section below. Examples: - $filter=City Eq 'Seattle' And OpenOnSunday Eq 'Y' - $filter=StartsWith(Locality,'San') |
| $format | Specifies the format of the HTTP response. The supported formats for the Query API are JSON and Atom. The default format is Atom. Example: $format=json |
| $inlinecount | Specifies whether or not to return a count of the results in the response. Possible values for this query option include: - allpages - none [default] Example: $inlinecount=allpages |
| $orderby | Specifies one or more properties to use to sort the results of a query. You can specify up to three (3) properties. Results are sorted in ascending order. Each type of query, such as Query by ID or Query by Property, has a default sort order for query results. If the $orderby option is not specified, query results are sorted using the default sort for that query type. For information about the default sort rules, see the documentation for each query type. Note: You cannot use the latitude and longitude properties to sort results. You can use the elevation property. Note: When you specify the $orderby query option, you must also specify a spatial filter or a $filter query option. For information about spatial filters, see Query by Area. Example: $orderby=PostalCode |
| $select | Specifies one of the following: 1. The data source properties to return in the response. If the $select query option is not specified or if it is set to "*" ($select=*), all data source properties are returned. Example: $select=Name,Phone 2. The intersection of the entity latitude or longitude or geographical area (defined by the entity geography) with the specified geography. If an entity has both latitude and longitude and geography properties in the schema, the intersection is computed with the geography property value. . To see definitions of the available geography types, see the types defined in Geography Types. While many different geography types are available, you will get the best performance if you use polygon, linestring or point types. Example:$select=intersection(POLYGON((9.86445 57.13876,9.89266 57.13876, 9.89266 56.94234,9.86445 56.94234,9.86445 57.13876))) |
| $skip | Specifies to not return a specified number of query results. For example, if this value is set to 50, then the first result that is returned is the 51st result. This option is not available in queries for the PointsOfInterest data source when using a Basic key. You can use the $skip query option with the $top query option to display a subset of the query results. For example, the following parameter combinations provide sets of 10 results at a time. &$skip=0&$top=10 [provides results 1 to 10] &$skip=10&$top=10 [provides results 11 to 20] Example: $skip=10 |
| $top | Specifies the maximum number of results to return in the query response. The default value is 25 and the maximum value is 250. You can return more than 250 results by making multiple queries and using the $skip parameter to step through the results. Example: $top=10 |
Supported $filter Comparison Operators
Note
When you are performing a StartsWith or EndsWith wildcard search, you cannot use the And or Or comparison operators to combine multiple $filter expressions.
| Operator | Description |
|---|---|
| Logical Operators | |
| Eq | Equal |
| Ne | Not equal |
| Gt | Greater than |
| Ge | Greater than or equal |
| Lt | Less than |
| Le | Less than or equal |
| And | Logical and Note: Not supported when combined with StartsWith or EndsWith wildcard searches. |
| Or | Logical or Note: Not supported when combined with StartsWith or EndsWith wildcard searches. |
| Not | Logical negation |
| Grouping Operator | |
| () | Precedence grouping |
Wildcard Search Functions
Note
Wildcard searches are not supported for the PointsOfInterest data source.
Wildcard searches do not support And or Or comparison operators. Therefore, you cannot combine a wildcard search with additional $filter expressions, and you cannot request more than one wildcard search at a time.
| Operator | Description |
|---|---|
| $filter=StartsWith(property,searchString) eq true | Finds all property values that start with ‘searchString’. Example:$filter=StartsWith(Locality,'San') eq true |
| $filter=EndsWith(property,searchString) eq true | Finds all property values that end with 'searchString' Example:$filter=EndsWith(Locality,'York') eq true |
Spatial Filter Query Options
Use the spatial filter in your query to set the area to search. The Query API offers four spatial filters.
Search a set distance from a location
spatialFilter=nearby(latitude,longitude,maximum distance in kilometers)
Search in a bounding box (an area defined by pairs of longitude and latitude values)
spatialFilter=bbox(South Latitude,West Longitude,North Latitude,East Longitude)
Search near a route
When you perform a nearRoute search, entities that are within one (1) mile or 1.6 kilometers are returned.
spatialFilter=nearRoute(latitude or ddress of route start,longitude or address of route end)
Search within a geographical area defined by a geography type
When you perform an ‘intersects’ search, entities that are within the geographical area defined by the specified geography are returned. Supported geography types include polygon and line string and are also used to define geography properties for entities. To see definitions of these types, see Geography Types.
spatialFilter=intersects('geography description')
Example: spatialFilter=intersects('POLYGON((9.86445 57.13876,9.89266 57.13876, 9.89266 56.94234,9.86445 56.94234,9.86445 57.13876))')