General notes

All data is in unicode and encoding used is UTF-8.

API accepts and generates only application/json requests and responses. All requests must have correct content negotiation headers to receive responses in correct format.

Some operations might not have any response body, like DELETE operation.

All create and update requests use flattened definitions. All other requests use normal definitions.

Dates and times

Dates and times are always in ISO 8601 standard format.

Items from catalogs

Some objects are from catalogs (sometimes referred as txtconstants). All objects representing full version also does have list_url-attribute which contains URL to full catalog.

Example of value from catalog:

{

"usage_state" : {

"id" : 14601,

"groupname" : "PREM_STATE",

"logical_txt" : "Käytössä",

"txt" : "In use",

"available": true,

"availability_start_ts": "2020-01-01T00:00:00",

"availability_end_ts": "2020-12-31T00:00:00",

"list_url" : "https://keycore.example.com/api/v2/txt_constants/groupname/PREM_STATE/"

}

}

Translations

API works mainly in english language, but some item properties can be translated to the user language for better understanding. One example is in Items from catalogs section. For catalog items txt attribute is translated one and logical_txt attribute is always in one fixed language.

By default translations are shown in the main system language.

To specify the language for translation the request header ACCEPT-LANGUAGE has to be set to some language code. Language codes are used as of ISO 639-1 two-letter language code specification. For example, if you want to return all the data in english, set Accept-Language: en header to the request.

Geographical locations

Geographical locations are passed as EWKT (Enhance WellKnown Text).

Example of location:

{

"location": "SRID=3067;POINT Z (454939.9781610000063665 6702826.5743100000545382 0.0000000000000000)"

}

Filtering

API list operation allows filtering response data according to query parameters specified in request. The main principle in API filtering is "if you see something in output data you can filter it". API filtering is based on request query parameters. If some query parameter with the same name as operation schema property is set to some value then the response data will be filtered to include only the objects with that property value. So, for example if object schema has identification property then you can filter with "identification=something" query paramater.

List operation supports hierarchical response data schemas. Filtering can be done by any hierarchy level. __ delimiter is used to traverse the levels in hierarchy. So, for example, if operation schema has some property named "state" which schema has it’s own property "id", then adding "state__id=something" to the request query parameters will filter the response data so only objects with that state id will be included.

You can traverse multiple hierarchy levels too if they are present in response data. So for example if response schema has property plan with it’s state, then you are able to filter by "plan__state__id=something".

When filtering a location property with specific coordinate system using SRID and the property value contains ";" as query parameter, for example location=SRID=3857;POINT Z (26.23103753785984 60.46132588573228 -7.928069680929184e-05). The symbol ";" must be urlencoded to (%3B) or else it splits EWKT into separate query parameters.

In addition to equality test, you can use other comparison functionality with trailing keywords via same __ delimiter. That functionality differs based on field types:

• For string fields:◦ istartswith: case-insensitive filter which includes only objects with property values which start with provided value

◦ startswith: case-sensitive filter which includes only objects with property values which start with provided value

◦ iendswith: case-insensitive filter which includes only objects with property values which end with provided value

◦ endswith: case-sensitive filter which includes only objects with property values which end with provided value

◦ contains: case-sensitive filter which includes only objects with property values which contain provided value

◦ icontains: case-insensitive filter which includes only objects with property values which contain provided value

◦ isnull: filter which includes only objects with property null values.

• For numerics (including dates):

◦ gt: filter which includes only objects with property values which are greater then provided value

◦ lt: filter which includes only objects with property values which are lower then provided value

◦ gte: filter which includes only objects with property values which are greater or equal to provided value

◦ lte: filter which includes only objects with property values which are lower or equal to provided value

◦ isnull: filter which includes only objects with property null values.

• For fields that are links to other endpoint or some id’s that is not in a list:

◦ in: filter which includes only objects with property values which are in the supplied in the list separated by commas.

• For spatial fields: contains, isnull, within, intersects, disjoint, touches, overlaps, covers, coveredby. See image for details.

Examples:

• usage_state__txt__istartswith=in - include only those objects with property’s "usage_state" property "txt" case-insensitively starting with "in" string.

• plan__state__txt__startswith=In - include only those objects with properties "plan" property "state" property "txt" case-sensitively starting with "In" string.

• creation_date__gte=2019-01-02T15:32:01 - include only those objects with property "creation_date" greater or equal to 2019-01-02 15:32:01

• location__within=POLYGON ((641503.89 6944059.81, 641406.52 6943933.87, 641369.48 6943772.48, 641474.25 6943704.74, 641873.78 6943735.96, 641848.38 6943975.15, 641607.08 6944167.76, 641653.11 6944102.15, 641503.89 6944059.81)) -include only those objects with property "location" within supplied area borders.

As of 3.2.8 product version, API also supports queries that exclude object by property value provided in query using a "not__" string preceeding the actual lookup:

Examples:

• not__type__txt__istartswith=Tie - exclude those objects with property’s "type" property "txt" value starting with "Tie" case-insensitively

• not__id=1390 - exclude those objects with property "id" value 1390.