Advanced Queries

The query parameter allows you to make detailed requests for the specific data you need that is not covered by the more general filters for that endpoint. This allows you to search for weather data based on a particular property of any data object within the API.

Using `query`

The following are supported formats for using query:

# Query using a single value and optional operator
/{endpoint}/{action}?query={property}:{operator}{value}
 
# Query using a range of values
/{endpoint}/{action}?query={property}:{min_value}:{max_value}

Option	Description	Default
`property`	Type: `string` (required)The property to perform the query on for the data object. The 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 regarding the short names of properties.
`value`	Type: `number` or `string` (required)If performing a query against a numerical field, this should be the minimum allowed value returned in the result set. If querying against a string field, this is the exact value of the property to search for.
`operator`	Type: `!` or `^` (optional)An optional operator to apply additional logic to the value, such as "not equal to" or "starts with": - !: "not equal" operation, which queries data where the specified `property` should not equal a given `value`. - ^: "starts with" operator, which queries data where the specified `property` starts with the given `value`
`min_value`	Type: `number` (required)Only used when performing numerical field queries. The results should only contain data whose `property` is greater than or equal to the specified `min_value`.
`max_value`	Type: `number` (optional)Only used when performing numerical field queries. The results should only contain data whose `property` is less than or equal to the specified `max_value`.

Performing string queries

Querying against a string property from the data object is an equal to operation. Therefore, you must provide the string exactly as what appears as the value for that property in order to return the proper results.

For example, to return a place object for Seattle, WA, you would request the following:

/places/search?query=name:seattle,state:wa

Not equal to example: The following will return up to 10 locations where the name is "blacksburg" and state is not equal to "va" (Virginia) under the places endpoint:

/places/search?query=name:seattle,state:!va&limit=10

Starts with example: The following will return up to 10 locations within the United States where the location name starts with the strong "minn" under the places endpoint:

/places/search?query=name:^minn,country:us&limit=10

Performing numerical queries

Performing a query against a numerical property is handled slightly differently than a string property in that it is an \>= - <= operation. If only the first value is provided, then all results whose value for that property is greater than or equal to (>=) the specified value is returned. The following request would return all storm cells that have an 80% probability or higher of containing hail:

/stormcells/closest?p=55403&query=hail:80

If both a minimum and maximum value are provided, then all results whose value for the property is equal to or in between the two values is returned. The following request would return all storm cells closest to the location whose probability of hail is >= 40% and <= 80%:

/stormcells/closest?p=55403&query=hail:40:80

You may want to perform a query in which you define a maximum value to cap the request with but not a minimum value. In this case, you would simply not provide the first value, which informs the API you want all results whose value is less than or equal to (<=) the specified value. For instance, the following request will return all storm cells whose probability of hail is 80% or less:

/stormcells/closest?p=55403&query=hail:0:80

Not equal to (!=): To perform a query that just ensures the numeric value is not equal to the value, just include an exclamation point in front of the value. For example, to obtain storm cells where the probability of hail is not equal to zero (0) use:

/stormcells/closest?p=55403&query=hail:!0

Chaining queries and filters

Multiple properties can be chained together in a single request to perform more complex AND/OR conditional queries. An AND operation is designated by separating your query strings by a comma (,). However, you would use a semicolon (;) character to separate your OR operations.

For example, the following places request would return all places whose name is either Seattle OR Austin:

/places/search?query=name:seattle;name:austin

The following request is commonly used to return all storm cells that have a tornadic signature, which also depends on the OR query operation:

/stormcells/closest?p=55403&query=tvs:1;mda:10

Using `NULL` in queries

The Xweather API allows requesting entries where a value is null or not null. A perfect use case may be to find the observations that did not report humidity:

/observations/98107?filter=allstations&query=rh:NULL

Or to avoid a null value for specific query properties by utilizing the !NULL option. Each endpoint query properties will support this option. The example below demonstrates how to ensure the reporting station contains a value for humidity:

/observations/98107?filter=allstations&query=rh:!NULL

Responses Sorting