Du er ikke logget på
The Geomatic Variables API
Technical Documentation

This section is written for programmers who are going to integrate the API.

Before reading this, you may find it useful to read the concepts section to understand what we mean by, for example, variables and domains.

Do you have a particular problem you need to solve (like getting the conzoom type of an address), you may be able find a specific recipe for this under the relevant data universe.

API Overview

The API is divided into three areas:

This remainder of section deals with some general concerns, that are not specific for those areas.

API Design

In general, the API follows principles of REST architecture, but will in some cases deviate from true REST. First of all we want return JSON, which in itself goes against being RESTful. In other cases adhering to REST principles would have made to API overly complex. Our main goal being that the API is flexible and simple for client to work with.

URL Structure

Fundamentally, the API is modelled around resources, which URLs looks as follows: 

https://apps.conzoom.eu/api/v1/:area/:country/:resource

where :resource is the name of the resource.

While the URL above will return all objects within the resource, the following will return the resource object with a specific identifier. 

https://apps.conzoom.eu/api/v1/:area/:country/:resource/:id

HTTP Verbs

The API is readonly so only GET requests are permitted.

Resource Objects in JSON

A request like above will return a resource object (provided one exists with the specified id). The resource object returned by our API will always be structured as follows:

{
    "self": {
        "type": string,
        "id": string,
        "url": string
    }
{resource-specific-objects}
}

The self object will always contain the 3 properties (none of them can be null):

Errors

The API uses standard HTTP status codes. A list of HTTP status codes can be found on Wikipedia.

If any error codes are returned then the body of the response will contain a JSON object with additional information about the error:

{
    "status": int,
    "title": string,
    //below fields may also be available
    "details": string,
    "help": string,
    "link": string,
    "request_link": string,
    "authenticated": bool
}

Media Types

The API can return the response as JSON or HTML. We inspect the accept header of the request to decide what to return. This means that if you put an URL in your browser you will get HTML back.

HTML responses are only intended for making the response easy to read. The structure and look of the HTML may change, so do not use HTML response as when coding against the API.

We provide the possibility to set the desired response format in the URL as en "." extention. So the following will return JSON even when used in an browser.

https://apps.conzoom.eu/api/v1/meta/dk/variables/cnztyp_g5.json

The extention method is intended for development and debugging purposes. Do not rely on this functionality in production use.

Authentication

In order to make requests to the API, you need a conzoom account. For how to get one, read here.

Basic Access Authentication over HTTPS

By default you would use basic access authentication whan calling the API, where you send your credentials in the authorization header formatted as “name:password” and base64-encoded. The credentials are not encrypted. However, the API works only over HTTPS.

An example of a valid basic authentication header can be seen below:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Token Based Authentication

If you are going to make your calls to the API in JavaScript executed in the browser, then you should obviously not reveal your username/password. In this case you should use our token based authentication.

You can request a token from Geomatic, which will then be used for authentication for each request to the API. The token is passed as an apikey query string parameter as follows in you request:

https://apps.conzoom.eu/api/v1/meta/dk/variables/cnztyp_g5?apikey=54f5ea5

The token is tied to your conzoom account and the domain that you are calling from, so you are only able to use the key from one domain.

If you need to use token based authentication, then write to your Geomatic contact with your conzoom account name and the domain that you want the token tied to. In case you do not have a specific contact, then you can use the contact form here.

The Meta Data API

This part of the API gives information about the variables, domains and other objects, that describes the actual data that are available through the values API.

The information that can be requested through the meta data API is also available as HTML pages here in the documentation pages. However in some cases you may want to programmatically get meta data about the variables that you use, in which case the API can be used.

The Meta Data resources are available at:

https://apps.conzoom.eu/api/v1/meta/:country/:resource

Meta Data Stability

Categories

By default, the set of categories of a variable is stable. By this we mean that no categories will be added or removed from a variable, and the underlying meaning behind a category will not change. Therefore it is safe to programmatically write business logic against the categories of a variable. So e.g. the conzoom type category with id = a2, will always be there and will always have the same meaning even if the variable is updated with new data. However, what can change is the name or description of a category. This can happen if we find a better name or description, or as part of an update of variables where some categories refer to specific absolute numbers such as income, then these numbers may change.

The Values API

This part of the variables API provides access to the actual data - the values of the variables, and gives you the ability enrich your own data with these.

URL Structure

In the values API the domain acts a resource, and the domain elements are the resource objects. So a particular domain element is reached using a GET request of the form:

https://apps.conzoom.eu/api/v1/values/:country/:domain/:id
An example being a unit address in Denmark which can be accessed at: 
https://apps.conzoom.eu/api/v1/values/dk/unadr/20670306

Optional Parameters

The following optional query string parameters can be passed as argument whenever retrieving a domain elements either by straight lookup via ID or via matching.

Even though the an URL like above will work, you should specify which variables you want returned in the request. This is done by using the vars parameter as described below.

Domain Element JSON

A request to get a domain element (like above) will return the domain element in following JSON format: 

{
    "self": {
        "type": string,
        "id": string,
        "url": string
    }
    "values": {
        "{variable1-id}": {value-of-variable1},
        "{variable2-id}": {value-of-variable2},
        ...
    }
}

As any resource object this contains a self object, where the id here is the id or key of the domain element.

The values object contains the values for the requested variables. It is layed out, such that for each name/value pair, the name is the id of the variable, and the value is the value of that variable.

If the value of a variable is null, this means that no value could be found for the particular domain object.

Value Types

The type of value that a variable returns differs from variable to variable. E.g. a street name variable returns its values as text, whereas an an income variable returns its values as numbers.

A variable will always return values of the same type, and that type is documented as part of the meta data of the variable.

Below is a complete list of all value types along with information about how they are represented in JSON.

Value Type ID JSON Type Description
Boolean bol true/false

If a value exists, then this is either true or false.

Category cat string / (object)

A variable of type category has an collection of categories, and it will return one of those categories as the value for a specific element of the domain. (It can also return null if no category applies to an element).

A category has an id and a name and optionally a description, and these can always be seen as part of the definition of a variable. Examples of category variables are conzoom type, age factor and municipality.

Date dat string

This can be a date, month or a year, depending on the accuracy of the variable.

In JSON this is represented by a string in the ISO 8601 date format, e.g., "2013-01-01T00:00:00"
Distribution dis object

A set of labeled fractional values that sum up to 1.0. E.g. { "0_11": 0.45, "over_11": 0.65}.

Fraction fra number

A fraction is always number between 0 and 1.

Guid gui string

A string containing a guid with lowercase hexadecimals. E.g. "dab6cead-948e-4ca1-99e7-c98e87f91804".

Integer int number

A whole number. E.g. 42.

Numeric num number

A decimal number. E.g. 42.0.

Point poi object

A set of coordinates. Either in the local UTM zone or in Latitude and Logitude depending on the provided parameters.
Text txt string

This is simply an unformatted text string. The maximum length of the text string is defined by the variable.

Category JSON

By default, the ID of the category will be returned as the value of a variable of type Category. The ID will always be a string. Full information about the category can be found through the meta data API at:

        https://apps.conzoom.eu/api/v1/meta/:country/variables/:var_id/categories
        https://apps.conzoom.eu/api/v1/meta/:country/variables/:var_id/categories/:cat_id

For example, the category with id a2 of the Danish conzoom type can be retrieved at: 

https://apps.conzoom.eu/api/v1/meta/dk/variables/cnztyp_g5/categories/a2

You can also see the possible categories as part of the documentation of the specific variables, e.g. here for the Danish conzoom type.

If you want the full category object out as the value in your response you can set cat=obj, in which case you will get an object in the following format: 

{
    "id": string,
    "name": string
}

For example:

https://apps.conzoom.eu/api/v1/values/dk/unadr/20670306?vars=cnztyp_g5&cat=obj

Distribution JSON

{
    "{category1-id}": number,
    "{category2-id}": number,
    ...
}

Point JSON

By default points come out as UTM coordinates (in the UTM zone of the country) with an X- and Y-part.

{
    "x": number,
    "y": number
}

If you want the coordinates out in latitude and longitute in your response you can set coords=latlong, in which case you will get a coordinates in the following format: 

{
    "lat": number,
    "long": number
}

Aggregated Values

When you operate with variables which do not have 1-1 data but as aggregate values, you can choose to get the values returned with the data level at which the value was fetched. Then the output will look as follows.

{
    "self" : { ... },
    "values" : {
        "{variable1-id}": {
            "value": {value-of-variable1},
            "data_level": {clusterset-id}
        }
    }
}

Here value will hold the actual value of the variable, and level is the id of the data level at which the value has been fetched. The API will always return the value of a variable from the most specific/accurate level where a value can be found.

Click link below to see an example of value returned with data level:

https://apps.conzoom.eu/api/v1/values/dk/unadr/20670306?vars=cnztyp_g5&level=id

Specific information about the data levels can be found at through the meta data API at: 

https://apps.conzoom.eu/api/v1/meta/:country/datalevels/:id

Lists of Domain Elements

In case you don't want a specific domain element, but rather a list of domain elements, then you can ommit the id part of the URL and instead use a criteria. You are only able to make criteria on one variable at a time, there is no way to combine criteria. The URL structure is then as follows: 

https://apps.conzoom.eu/api/v1/values/:country/:domain
An example being accessing all unit addresses on a street: 
https://apps.conzoom.eu/api/v1/values/dk/unadr?where=pcstreet_key=4569&top=5000

Optional Parameters

The following optional query string parameters can be passed as argument whenever retrieving a list of domain elements.

Simple Criteria

Simple criteria filter the list of domain elements based on a single variable. A simple criteria consists of a variable id followed by equals and then the required value (or values seperated by comma). If for example you want all domain elements on a specific street, then append where=pcstreet_key=4569 to the URL. Here 4569 is the id of a specific street.

You also can make a criteria that requires a variable to be one of several values. For example where=unadr_usage_v2=120,121,130.

It is also possible to test of a variable has a value. This could be used for find building that have some value for the "Fredning" variable by appedning where=bld_consvtn has value.

Geographical Criteria

Geographical criteria is not part of the standard API access. If you do not have access to this feature, you need to contact your Geomatic sales representative.

As an alternative to the simple where criteria, it is possible to create a geographical criteria based on the location of addresses and a user provided circle or polygon. An example of finding all addresses within a circle: 

https://apps.conzoom.eu/api/v1/values/dk/acadr?where=acadr_loc:in(circle(x:532390,y:6147135,r:100m))

The center of the circle can either be given as X,Y coordinates in UTM32 projection, or as latitude and longitude. The radius can be given either in meters(m) or kilometers(km). An example of using latitude and longitude can be seen below. 

https://apps.conzoom.eu/api/v1/values/dk/acadr?where=acadr_loc:in(circle(lat:56.362564,long:8.621231,r:90m))

An example of finding all addresses within a polygon: 

https://apps.conzoom.eu/api/v1/values/dk/acadr?where=acadr_loc:in(polygon(xy,[[[721825,6172320],[721890,6172320],[721830,6172390]]]))

The center of the vertices of the polygon can either be given as X,Y coordinates in UTM32 projection, or as latitude and longitude. An example of using latitude and longitude can be seen below. 

https://apps.conzoom.eu/api/v1/values/dk/acadr?where=acadr_loc:in(polygon(latlong,[[[12.5253,55.64601],[12.52641,55.64598],[12.52551,55.64663]]]))

Complex Criteria

Complex criteria is not part of the standard API access. If you do not have access to this feature, you need to contact your Geomatic sales representative.

If the list of domain elements needs to be filtered based on more than one variable a complex criteria is needed. We currently support joining multiple simple and geographical criteria with and and or. To do this each simple or geographical criteria needs to be enclosed in parentheses and then seperated by either and or or. An example of this can be seen below. 

https://apps.conzoom.eu/api/v1/values/dk/unadr?where=(floor=02) and (acadr_loc:in(polygon(latlong,[[[12.5253,55.64601],[12.52641,55.64598],[12.52551,55.64663]]])))

If both and and or is used in the same criteria then and takes precedence as would be expeced from any other language. This means that in the following will match all adrresses on the second floor and addresses that are on the right on the third floor. 

https://apps.conzoom.eu/api/v1/values/dk/unadr?where=(floor=02) or (floor=03) and (suite=th)

If only addresses to the right is wanted on either the second or the thrid floor then extra parentheses are needed, as shown below. 

https://apps.conzoom.eu/api/v1/values/dk/unadr?where=((floor=02) or (floor=03)) and (suite=th)

This example could also be written simpler like this. 

https://apps.conzoom.eu/api/v1/values/dk/unadr?where=(floor=02,03) and (suite=th)

Domain Element List JSON

A request to get a list of domain elements (like above) will return the domain elements in the following JSON format: 

{
    "meta": {
        "objects_cap": number,
        "objects_cap_applied": boolean,
        "filter": string
    }
    "objects": [
domain element object,
domain element object,
        ...
    ]
}
The objects list contains domain element objects as described earlier.

The Match API

When you do not posess an id to perform straight look up on domain elements, you can take advantage of our matchers.

A matcher is an algorithm, which based on some free-text input will try to match this input against elements in the domains. An example of a matcher is Geomatic's Danish Geocoder. It can for instance match text input (e.g. streetname, housenumber and postcode) against all unit addresses in Geomatic's Address Database.

A matcher works in such a way that it will attempt to find a single unique match, and will never return multiple matches.

Under each data universe you can find the matchers that applies to the particular universe. You can also read documentation about a specific matcher in matchers section.

The Match Request

Unlike the other areas of the API, the match API is not modelled in a REST-ful way around resources, but instead as an operation that takes some input and returns a match response. The match response will contain a match (if one is found) along with information about how good the match was.

You can perform a match by making GET request of the form:

https://apps.conzoom.eu/api/v1/match/:country/:matcher?in_x1=?&in_x2=?...

where :matcher is the id of the matcher, that you want to use.

Below is a concrete example of a call to Geomatic's Swedish Geocoder.

https://apps.conzoom.eu/api/v1/match/se/geocoder?in_adr=Elevvägen 10, 61336

Required Parameters

You must provide the input to the match using the in_* query strings parameters. You can see the available in_* parameters under the documentation of the matcher you want to use. The more precise in_*-parameters you use, the better is the chance of a match.

Optional parameters

You can add the following optional arguments as query string parameters:

Match Response JSON

The response of a match request will look as follows:

{
  "matchinfo": {
    "{matchinfo1}": {category},
    "{matchinfo2}": {category},
    ...
  },
  "match": {domain-element}
}

match contains the actual match, and is an element of a domain. So this object is the same object that is being returned by performing a straight lookup via id in the Values API. You can read how this is formatted in here. If no match is found, then match will be null.

Some matchers can match across different domains, so there is no guarentee that the match will contain an object if a particular type. However, you can always inspect the self to see the type of the matched domain element object. A matcher will always try to match the most specific domain, so it would only return an access address if it could not match a unit address.

matchinfo will hold information about how good the match was. This is never null, even when there is no match. matchinfo is actually a collection of variable/value pairs like the the values collection of the domain element, where the variables are some special match variables provided by the matcher. These match variables all have value type category, and you can find more information about the under the documentation of the specific matcher.

Batching Match Requests

If you need to match a lot of inputs at the same time, it can be slow to make a match request for each input. In this scenario you can use the batch method, which lets you make a request containing multiple inputs.

Batch Request

A batch request is made by making a POST request to the following URL:

https://apps.conzoom.eu/api/v1/match/:country/:matcher/batch

Where :matcher is the id of the matcher, that you want to use.

The input for the matcher is provided in the body of the request and must be encoded as a JSON object in the following format.

{
  "client_input_id1":{
    "in_arg1": "...",
    ...
  }, 
  "client_input_id2":{
    "in_arg1": "...",
    ...
  }, 
  ...
}

So this JSON object is a basically a hash (name/value pairs) where the name is an ID (that is unique within the request) provided by the client, and the value is an object where the names refers to the input arguments of the matcher, and the values is the value for the particular argument and input. For specific input arguments see the documentation of the matcher you want to use.

An example of a batch request body that will work for the Swedish Geocoder is seen below: 

{
  "john":{
    "in_adr":"Bergsgatan 24, 21422 Malmö"
  }, 
  "eric":{
    "in_str":"Bergsgatan 5",
    "in_pcode":"21422 Malmö"
  }
}

There is an upper limit of 5MB or 2500 records (which ever comes first) on batch requests. Do you hit this limit you must split your inputs into multiple request.

The optional parameters for the batch request are the same as for the standard match request, and they are provided the same way, i.e. as query string parameters.

Batch Response

The response of a batch request is a JSON object where the names are the client input IDs provides in the request. And the values contain the corresponding match objects, which look exactly like what is being returned in the standard match request. So the response of the example request above will look like this:

{
  "eric": {
    "matchinfo": {
      "{matchinfo1}": {category},
      "{matchinfo2}": {category},
      ...
    },
    "match": {domain-element}
  }, 
  "john": {
    "matchinfo": {
      "{matchinfo1}": {category},
      "{matchinfo2}": {category},
      ...
    },
    "match": {domain-element}
  }, 
  ...
}

The results may be in a different order than the input, so the client input IDs should always be used when matching the matches in the response against the input.