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.

The following is the basic format for queries:

/ACTION?query=PROP:VAL
/ACTION?query=PROP:!VAL
/ACTION?query=PROP:^VAL
/ACTION?query=PROP:MIN_VAL:MAX_VAL

 

PROP 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.
VAL/MIN_VAL 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.

Not Equal Too - If the VAL is preceded by an exclamation point (!) then a "not equal to" query is performed.

Starts With - If the VAL is preceded by an caret (^) then a "starts with" query is performed. This type of query is often used for auto complete queries.
MAX_VAL Only used when performing numerical field queries, this is the maximum allowed value to be returned in the result set.

String Property 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

Numerical Property 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 an query that just ensure 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 a 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 the query parameters

Avoid a null value for specific query properties by utilizing the !NULL option built into the Aeris API. Each endpoints 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