ARLAS Exploration API

The ARLAS API makes the ARLAS catalog available for exploration and browsing. The catalog contains collections of geo-referenced elements. Every element has a geometry, a centroid, a timestamp and a set of fields specific to the collection.

URL Schema

The table below lists the URL endpoints and their optional "parts". A part is composed of optional parameters. The parameters are separated with the character &.

When multiple collections are permitted ({collections}), the comma is used for separating the collection names.

All URLs are accessible both with GET and POST requests. For POST requests, URL parts are passed as a JSON representation.

URL Parts

Part: aggregation

The [aggregation] url part allows the following parameters to be specified:

The agg parameter should be given in the following format :

• {type}:{field}:interval-{interval}:format-{format}:collect_field-{collect_field}:collect_fct-{function}:order-{order}:on-{on}:size-{size}

Where the {type}:{field} part is mandatory

The other parts must be specified or not depending on the aggregation type. All the cases are sum up in the following table.

Example: agg=datehistogram:date:interval-20day:format-dd.MM.yyyy&agg=term:sexe:collect_field-age:collect_fct-avg:order-asc:on-result:size-5

The sub-parameters possible values are:

(1) Each aggregation type ({type}) has its own type of interval. The table below lists the semantic of the interval sub-parameter.

(2) (collect_field,collect_fct) should both be specified. It's possible to apply multiple metric aggregations by defining multiple (collect_field,collect_fct) couples. They should be unique in that case. The metrics geobbox and geocentroid are returned as features collections.

(3) When on is result, then (collect_field,collect_fct) should be specified. Except when collect_fct = geobbox or geocentroid, then on=result is prohibited .

(3') If on is equal to result and two or more (collect_field,collect_fct) couples are specified, then the order is applied on the first collect_fct different from geobbox and geobbox".

Example: agg=term:sexe:collect_field-location:collect_fct-geobbox:collect_field-age:collect_fct-avg:collect_field-height:collect_fct-max:order-asc:on-result

The order is applied on the first collect_fct avg (that is different from geobbox).

(4) If one value is specified then regular expressions can be used (only in this case) and buckets matching them will be created. If more than one value are specified then only buckets matching the exact values will be created.

(5) Available aggregated geometries :

• bbox: returns the data extent (bbox) inside the bucket.
• centroid: returns the centroid of data inside the bucket.
• cell: returns the tile extent (zxy or geohash) of each bucket. This form is supported for geohash and geotile aggregation type only.
• cell_center: returns the 'center' of the tile extent that represents the bucket. This form is supported for geohash and geotile aggregation type only.

(6) The response:

• For _aggregate service: the aggregated geometries are returned in geometries list in the json response. Each object inside this list has : the reference to the aggregated form, the geojson geometry and an attribute is_raw set to false.
• For _geoaggregate service: each bucket of the aggregation will be represented with as many features (in a feature collection) as there are specified aggregated geometries. The properties of each feature has :
  • geometry_ref attribute that informs which aggregated form is returned.
  • geometry_type attribute set to aggregated.

(7) Any field of the collection whose type is geo-point or geo-shape can be set in raw_geometries.

• Sort fields are optional. If no sort is specified, an ascending sort on collection.params.timestamp_path is applied.
• A sort field can be preceded by '-' for descending sort. Otherwise the sort is ascending

(8) The response :

• For _aggregate service: the aggregated geometries are returned in geometries list in the json response. Each object inside this list has : the reference to the geometry path, the used sort, the geojson geometry and an attribute is_raw set to true.
• For _geoaggregate service: each bucket of the aggregation will be represented with as many features (in a feature collection) as there are specified raw geometries. The properties of each feature has :
  • geometry_ref attribute that informs which geometry path is returned.
  • geometry_type attribute set to raw.
  • geometry_sort attribute that informs how the geometry path is fetched (with what sort).

  • Example: raw_geometries-geo_field1,geo_field2 || raw_geometries-geo_field(-field1,field2) || raw_geometries-geo_field1(field1);geo_field2(field2,field3) (9)

• Example: fetch_hits-3(-timestamp, geometry). The 3 last positions are retrieved for each bucket

Note that if the number of hits to fetch is not specified, 1 is considered as default.

• Example: fetch_hits:(-timestamp, geometry). The last position is retrieved for each bucket

The table below shows the metric dimensions for cells covered by various string lengths of geohash. Cell dimensions vary with latitude and so the table is for the worst-case scenario at the equator.

agg parameter is multiple. Every agg parameter specified is a subaggregation of the previous one : the order matters.

For _geoaggregate service, the first (main) aggregation must be geohash,or geotile.

Part: filter

Available filter parameters

The filter url part allows the following parameters to be specified:

Filter parameters algebra

For each parameter, you can provide multiple filters. There are 2 different ways to do this :

• in distinct filter parameters = AND operator between filters
• in the same filter parameter as a semi-colon separated list = OR operator between filters

Of course, you can combine both way to handle complex multiple filters for each filter parameter type.

f parameter syntax

The :range: operator has a specific syntax to indicates if range bounds are taken into account or not.

On top of that, :range: operator supports generic aliases to represent collection configured fields : * $timestamp refers to collection's timestamp field.

Example: f=city:eq:Toulouse&f=city:eq:Bordeaux&f=$timestamp:range:[0<1490613808000]

Special syntax for date queries using lt, gt, lte, gte and range operations

In the case of lt, gt, lte, gte, range operations that are applied on date fields, the date values have four possible forms :

• a timestamp in millisecond OR a date in a custom format(*).
• a timestamp in millisecond OR a date in a custom format(*) followed by || and followed by a date operation (+1h, /M, -2y, ...)
• now
• now followed by a date operation (+1h, /M, -2y, ...)

The date expression: timestamp:gte:now-1M/M substracts 1 month from now then the resulted date is rounded down to the beginning of the month. Assuming now is 2018-06-15. timestamp:gte:now-1M/M is equivalent to timestamp:gte:2016-05-01

Partition filtering

filter part can also be passed in request header partition-filter as a serialized json for partitioning concerns.

Example: curl --header "partition-filter: {"f":[[{"field":"city","op":"eq","value":"Bordeaux"}]]}" https://api.gisaia.com/demo/arlas/explore/cities/_count

When dealing with multi collections, filter can also be specified in a JSON map , e.g.:

Example: curl --header "partition-filter: {"mycollection1": {"f":[[{"field":"city","op":"eq","value":"Bordeaux"}]]}}" https://api.gisaia.com/demo/arlas/explore/cities/_count

You can pass several filter in partition-filter, separated by comma :

Example: curl --header "partition-filter: {"f":[[{"field":"city","op":"eq","value":"Bordeaux"}]]},{"f":[[{"field":"city","op":"eq","value":"Paris"}]]}" https://api.gisaia.com/demo/arlas/explore/cities/_count

In this case a OR combination is done.

Column filtering

A comma-separated list of columns can be passed in request header column-filter. Wildcards are supported.

A column filter stands for the fields that are available to a request body:

• if a request body field doesn't belong to the column filter, a 403 is returned with the message The field '%s' isn't available or The fields '%s' aren't available;
• only fields that belong to the column filter can be returned.

A column filter can be related to a collection, e.g. mycollection:myfield or it can be related to every collection, e.g. myfield. Trying to access a collection with no available field returns a 403. Collection names can be omitted or end with a '*'.

Examples of column-filter:

• mycollection:params.city,mycollection:params.country makes available params.city and params.country for collection mycollection
• mycollection*:params.city makes available params.city for all collections whose names start with mycollection
• params, params*, params.*, *params make available params.city, params.country, params.weight, and so on. for every collection
• params, :params, *:params make available params and subfields for every collection
• * makes all fields available
• *.* makes only subfields available, e.g. params.city and params.country but not id
• `` (empty value) makes all fields and collections forbidden.

If no column filter, then no filtering is done. An empty column filter will forbid all collections and columns.

The following endpoints use this header:

On top of that, a query ("q" parameter) filter MUST target a specific field:

• fullname:john is valid
• john isn't valid and will return a 403
• params*:john isn't valid neither and will return a 403

If a projection with an includes parameter is used, then:

• included fields that are wildcards aren't checked; they do not return a 403 if they don't match the column filter;
• and only included fields that match the column filter are returned

Part: form

The form url part allows the following parameters to be specified:

Example: pretty=true&flat=false

Part: field

The compute url part is used in _compute service.

!!! note 'Note'

- `max` : the maximum value of the given field. Field should be numeric or date.
- `min` : the minimum value of the given field. Field should be numeric or date.
- `avg` : the average of the given field values. Field should be numeric or date.
- `sum` : the sum of the given field values. Field should be numeric or date.
- `cardinality` : the number of distinct values of the given field.
- `spanning` : the range value (max-min) of the given field. Field should be numeric or date.
- `geobbox` : the extend of data based on the given geo-point field.
- `geocentroid` : the centroid of data based on the given geo-point field.

!!! info '_range endpoint is removed'

Starting from v13.7.0, `_range` endpoint is removed. You can use the endpoint `_compute` instead.
- If you used `_range` to get the `(max-min)` value of the given field, then you can call :  `_compute?field=your_field&metric=spanning`
- If you used `_range` to get separately the `min` and `max` values of the given field, then you can call `_compute` twice using `_compute?field=your_field&metric=min` and `_compute?field=your_field&metric=max`

Example: field=timestamp

Part: projection

The projection url part allows the following parameters to be specified:

Example: include=*&exclude=city,state

Part: returned_geometries

The returned_geometries url part can be specified in _search & _geosearch services:

Example: include=*&exclude=city,state

Part: suggest

The suggest url part allows the following parameters to be specified:

Example: field=recommended

Part: page

The page url part allows the following parameters to be specified:

sort parameter

after and before parameter

OpenSearch

If enabled, ARLAS offers an Opensearch Description document (/arlas/ogc/opensearch/{collection}).