Get in touch
Get in touch

Query parameter reference

Datagraphs API makes a range of query parameters available for organizing and refining searches for Datasets and Concepts. 

Definitions

sort Sorts the results in the response using a specified field and direction, eg sort=property1:asc,property2:desc
pageNo The page number indicating which set of results should be returned in the response, eg pageNo=2
pageSize The number of results to return in the response, eg pageSize=10
q Full text search, eg q=name
facets Facets to be listed, eg, facets=type
dateFacets Date facets, eg dateFacets=publishedDate:1d:1w:1M
embed List of ids of related properties to be embedded in the response, eg embed=id1,id2,id3 or for all properties embed=_all
ids List of Concept ids to be returned (separated by a comma), eg ids=id1,id2,id3
filter A expression that filters a request. It is a string that takes the form  {property}:{operator}{value} or uses a special function

Building a filter expression

Filter expressions can be constructed from a property, value and optional operator. More complex queries can use a filter function (see below).

In its simplest form a filter expression consists of a property and a value, eg filter=property1:value1, where the separator (:) is equivalent to "=". Adding an operator allows for different types of comparisons. 

Filter expressions can be combined using  , (AND) or | (OR). Using parentheses around combinations of expressions – eg ({expression1},{expression2}) – overrides operator precedence.

The following defines the rules for each element in a constructed filter expression:

Property A path representing the field to filter on.
  • It matches [a-zA-Z_][a-zA-Z0-9_.].
  • It supports . separated paths.
  • It can contain only alpha-numeric characters and _.
  • It cannot contain whitespace.
  • It must start with a letter.
Operator Used to compare values (on its own is roughly =); optional.
  • - not
  • > greater than
  • >= greater than or equals
  • < less than
  • <= less than or equals
  • [ value, value, ... ] in group
Value A string containing the value to match the expression against.
  • It can contain whitespace.
  • Dates and datetimes should be in ISO 8601 format.

Filter functions

Functions for more complex queries follow the format  filter=_functionName(arg1, arg2, etc). The following are supported:

_within()

Search for Concepts within a given area. 

Coordinates can be provided either as latitude and longitude in the format  (lat, long), or as a geohash. If two coordinates are provided, they define the top left and bottom right corners of the search area as a bounding box. Three or more coordinates define the search as a polygon.

NB This function can only be used with Concepts whose properties include either a latitude/longitude pair or a geohash property.

_near()

Find Concepts within range of a given location. 

Coordinates can be provided either as latitude and longitude in the format  (lat, long) or as a geohash.

The following units are supported for distance:

  • mi – miles
  • km – kilometres
  • m – metres
  • cm – centimetres
  • mm – millimetres

NB This function can only be used with Concepts whose properties include either a latitude/longitude pair or a geohash property.


Filter examples

The following expressions are all based on the same query, a Get all Concepts:

– where  string1 equals value1

filter=string1:value1

– where  string1 equals value1 and string2 equals value2

filter=string1:value1,string2:value2

– where  string1 equals value1 and string2 does not equal value2<br>

filter=string1:value1,string2:-value2

– created between  2020-01-01 and 2020-02-01<br>

filter=createdDate:>=2020-01-01,createdDate:2020-02-01

– created or modified since  2020-01-01

filter=createdDate:>=2020-01-01|lastModifiedDate:>=2020-01-01

– where string1 equals value1 or value2

filter=string1:[value1,value2]

– where  string1 equals value1 and it was created or modified since 2020-01-01

filter=string1:value1,(createdDate:>=2020-01-01|lastModifiedDate:>=2020-01-01)

– within 100 miles of coordinates (-40, 70)

filter=_near((-40, 70), 100mi)

– within a polygon with points (-40, 70), (-30, 60), (-35, 60)

filter=_within((-40, 70) (-30, 60), (-35, 60))

– within a box with top left corner (-40, 70) and bottom right corner (-30, 60)

filter=_within((-40, 70) (-30, 60))