Geocoder

Geocode API is a service for finding geographical coordinates and structured output for entered addresses. Service analyses the input text and responds by the list of address point candidates, ordered by relevance.

Baltic Geodata Marketplace Geocode API is based on Photon GC.

Process

Process chart

Name Type Explanation
Is request valid? Gateway Application verifies request parameters
Error response Message End Application creates error response according to "Verification" chapter
Request geocode information from database Action API queries database with request parameters
Response message Message End Application creates response message according to "Response message" chapter

Request parameters

Request consists of the following URI parameters:

Parameter Possible values Default value Required Description
q string - Yes The address you want to geocode.
By one request it's possible to geocode only one address
apikey string - Yes Your authorisation key
region est, lva, ltu - No Dataset id by country such as est, lva, ltu etc. The codes are set according to ISO-3166-1 standard. Defines the area where data is searched from.
This parameter may be specified multiple times, to merge results from multiple datasets. Example: "...&region=est,ltu&..."
lang et, lv, lt - No If lang is not defined, output is given in all available languages.
If lang is defined, addresses are searched and output is given in these languages only.
type xml, json json No The format in which output should be generated
rs std, reverse, lv std No Rule set id. Some datasets may support multiple rule sets for filtering, ranking and formatting the matches in the response.
crd latitude,longitude - No Comma separated coordinates of the center point of prioritised area.
If used, results nearer to the specified point are ranked higher in the list of results.
limit integer 10 No Maximum number of address point candidates returned.
Max value is 25.
crs EPSG code 4326 No Spatial reference system of the result. Any proj.4 epsg code can be used
include_apartments true, false false No By default, the service does not return apartments. If include_apartments=true, each address with apartment is returned as a separate address object. For example, when a building has six apartments, six address objects will be returned in the output.
geometry point, line, polygon all geometry types No For defining object by geometry type - either address objects (points), street lines (lines) or administrative/territorial units (polygons).
By requesting polygon, also multi polygons are included, and by requesting line, also multiLines are included.
It's possible to define more than one value at a time - for example: &geometry=point,line,polygon
Autocomplete
Without parameter		 - - - JGC assumes the input address is only the beginning of the actual address (useful for displaying suggestions when user types an address into an edit box e.g. on a web page).

Request URL example

https://api.geodatahub.eu/gc?q=[address to geocode]&apikey=[API_KEY]&type=[response type]&lang=[output language]&limit=[output limit]&crs=[EPSG code]&geometry=[geometry type]

Verification

Verification errorCode errorName errorDescription
Is q present in request? 400 Bad Request Required String parameter 'q' is not present
Is API key in request? 400 Bad Request No API key found in request
Is API key correct in request? 401 Unauthorized Invalid authentication credentials
Is API key active? 403 Forbidden Inactive API key found in request
Is region defined correctly in request? 501 Not Implemented Unknown region: '...'
Is language defined correctly in request? 501 Not Implemented Unsupported language '...'. Supported languages: lt,en,lv,et
Is output format defined correctly in request? 400 Bad Request Incorrect output format(type) requested
Is rule set id defined correctly in request? 501 Not Implemented Unknown rule set id: '...'
Is crd value defined correctly in request? 400 Bad Request Incorrectly defined crd value in request
Is limit defined correctly in request? 400 Bad Request Incorrectly defined limit value in request. Maximum value: 10
Is EPSG code correct in request? 400 Bad Request Unknown coordinate system:...
Is include_apartments value defined correctly in request? 400 Bad Request Incorrectly defined 'include_apartments ' value in request

Response parameters

  • HTTP status = 200;
  • Body consists of the following values:
Parameter Type Presence depends on request parameter? Description
name string No Searched string - input q
  properties - - -
    full_address string No Formatted address string, exact format depends on the request parameter rs
    country string No Country code
    level0...level[n] string No Address components by levels. Real content depends on country specifics and can be understood by conversion table.
    apartment string Yes, if include_apartments=true Apartment number
    postal_code string No Postal code
    adob_type string No Address object type (general code). Reference table of address object type local codes by countries.
Currently available for Estonian data only.
    pop integer No Value of population of populated places Can be used for ranking purposes.
    extended_data - - -
      crs string No Spatial Reference (EPSG) code of query and response. If not specified by request parameter, default value "EPSG:4326" is given.
      centroid double No Center coordinates of the output object.
      is_address boolean No If true, output is an address object.
If false, output is an address component (e.g. municipality, settlement unit, street).
  geometry - - -
    type string No Geometry type. Possible values: Point, MultiLineString or MultiPolygon
    coordinates double No Geographical coordinates for each address object.
If not specified by request parameter, coordinates are given in EPSG:4326.
  bbox double No Corner coordinates of the output object

Response examples

{
  "type": "FeatureCollection",
  "name": "riia 24, tartu",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "full_address": "Eesti, Tartu maakond, Tartu linn, Tartu linn, Riia tn 24",
        "country": "EST",
        "level1": "Tartu maakond",
        "level2": "Tartu linn",
        "level3": "Tartu linn",
        "level5": "Riia tn",
        "level7": "24",
        "postal_code": "51010",
        "adob_type": "NB",
        "extended_data": {
          "crs": "EPSG:4326",
          "centroid": "26.717089,58.371547",
          "is_address": true
        }, 
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          26.717089,
          58.371547
        ]
      },
      "bbox": [
        26.717089,
        58.371547,
        26.717089,
        58.371547
      ]
    }
  ]
}
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:kml
  xmlns:gx="http://www.google.com/kml/ext/2.2"
  xmlns:ns2="http://www.opengis.net/kml/2.2"
  xmlns:atom="http://www.w3.org/2005/Atom"
  xmlns:xal="urn:oasis:names:tc:ciq:xsdschema:xAL:2.0">
  <ns2:Document>
    <ns2:name>riia 24, tartu</ns2:name>
    <ns2:Placemark>
      <xal:AddressDetails>
        <xal:AddressLines>
          <xal:AddressLine Type="full_address">Eesti, Tartu maakond, Tartu linn, Tartu linn, Riia tn 24</xal:AddressLine>
          <xal:AddressLine Type="country">EST</xal:AddressLine>
          <xal:AddressLine Type="level1">Tartu maakond</xal:AddressLine>
          <xal:AddressLine Type="level2">Tartu linn</xal:AddressLine>
          <xal:AddressLine Type="level3">Tartu linn</xal:AddressLine>
          <xal:AddressLine Type="level5">Riia tn</xal:AddressLine>
          <xal:AddressLine Type="level7">24</xal:AddressLine>
          <xal:AddressLine Type="postal_code">51010</xal:AddressLine>
          <xal:AddressLine Type="adob_type">NB</xal:AddressLine>
        </xal:AddressLines>
      </xal:AddressDetails>
      <ns2:ExtendedData>
        <ns2:Data name="is_address">
          <ns2:value>true</ns2:value>
        </ns2:Data>
        <ns2:Data name="bbox">
          <ns2:value>26.717089,58.371547,26.717089,58.371547</ns2:value>
        </ns2:Data>
        <ns2:Data name="centroid">
          <ns2:value>26.717089,58.371547</ns2:value>
        </ns2:Data>
        <ns2:Data name="crs">
          <ns2:value>EPSG:4326</ns2:value>
        </ns2:Data>
      </ns2:ExtendedData>
      <ns2:Point>
        <ns2:coordinates>26.717089,58.371547</ns2:coordinates>
      </ns2:Point>
    </ns2:Placemark>
  </ns2:Document>
</ns2:kml>

Data sources and updates

Address data used in GDH Geocode API is based on national address databases, maintained by state institutions, including Maa-amet (Estonian Land Board) for Estonian addresses and Valsts Zemes dienests (Latvian State Land Service) for Latvian addresses. GDH address data is updated on a quarterly basis.