Events filtration

Geo position

You can add a geo position during event creation.

The geo position is represented as a JSON with GPS coordinates of the geographical point:

• longitude - geographical longitude in degrees

• latitude - geographical latitude in degrees

The geo position is specified in the “location” body parameter of the event creation request. See create new events.

You can use the geo position filter to receive all the events that occurred in the required area.

Geo position filter

A geo position filter is a bounding box specified by coordinates of its center (origin) and some delta.

It is specified using the following parameters:

• origin_longitude

• origin_latitude

• longitude_delta

• latitude_delta

The geo position filter can be used when you get events, get statistics on events, and perform events matching. See the EventsReferenceManual documentation for details.

Geo position filter is considered as properly specified if:

• both origin_longitude and origin_latitude are set.

• neither of origin_longitude, origin_latitude, longitude_delta, latitude_delta is set.

If both origin_longitude and origin_latitude are set and longitude_delta is not set - the default value is applied (see the default value in the EventsReferenceManual).

Warning

Read the following recommendations before using geo position filters.

The general recommendations and restrictions for geo position filters are:

• Do not create filters with a vertex or a border on the International Date Line (IDL), the North Pole or the South Pole. They are not fully supported due to the features of database spatial index. The filtering result may be unpredictable;

• Geo position filters with edges more than 180 degrees long are not allowed;

• It is highly recommended to use the geo position filter citywide only. If a larger area is specified, the filtration results on the borders of the area can be unexpected due to the spatial features.

• Avoid creating a filter that is too extended along longitude or latitude. It is recommended to set the values of deltas close to each other.

The last two recommendations exist due to the spatial features of the filter. According to these features, when one or two deltas are set to large values, the result may differ from the expected though it will be correct. See the Filter features section for details.

Filter performance

Geo position filter performance depends on the spatial data type used to store event geo position in the database.

Two spatial data types are supported:

• GEOMETRY: a spatial object with coordinates expressed as (longitude, latitude) pairs, defined in the Cartesian plane. All calculations use Cartesian coordinates.

• GEOGRAPHY: a spatial object with coordinates expressed as (longitude, latitude) pairs, defined as on the surface of a perfect sphere, or a spatial object in the WGS84 coordinate system.

For a detailed description, see geometry vs geography.

Postgres

Geo position filter is based on the ST_Covers PostGIS function supported for both geometry and geography type.

Filter features

Geo position filter has some features caused by PostGIS.

When geography type is used and the geo position filter covers a wide portion of the planet surface, filter result may be unexpected but geographically correct due to some spatial features.

The following example illustrates this case.

An event with the following geo position was added in the database:

{
    "longitude": 16.79,
    "latitude": 64.92,
}

We apply geo position filter and try to find the required point on the map. The filter is too extended along the longitude:

{
    "origin_longitude": 16.79,
    "origin_latitude": 64.92,
    "longitude_delta": 2,
    "latitude_delta": 0.01,
}

This filter will not return the expected event. The event will be filtered due to spatial features. Here is the illustration showing that the point is outside the filter.

You should consider this feature to create a correct filter.

For details, see Geography