Reverse geocoder

Reverse Geocode API is for finding readable address or place name for geographical coordinates (point location).

Process

Name	Type	Explanation
Is request valid?	Gateway	Application verifies request parameters
Error response	Message End	Application creates error response according to "Verification" chapter
Request reverse 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
`lat`	double		Yes (A)	Latitude. E.g. 58.37
`lon`	double		Yes (A)	Longitude. E.g. 26.71
`x`	double		Yes (B)	X coordinate (for example in LKS-92 (EPSG:25884) coordinate system)
`y`	double		Yes (B)	Y coordinate (for example in LKS-92 (EPSG:25884) coordinate system)
`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.
`apikey`	string		Yes	Your authorisation key
`rs`	string			TO BE SPECIFIED
`type`	xml, json	json	No	The format in which the output should be generated.
`crs`	string	4326	B	Spatial reference system of the query and response. Supported values include EPSG:4326 (i. e. WGS84 geographical coordinates) and EPSG:3301 (i. e. L-EST97, the Estonian national projected coordinate system), as well as the EPSG codes for the UTM projections.
`limit`	integer	1	No	Max value 25

Request URL example

https://api.geodatahub.eu/rgc?apikey=[API KEY]&y=[Y coordinate]&x=[X coordinate]&lang=[output language]&type=[response type]&crs=[EPSG code]&limit=[output limit]

Verification

Verification	errorCode	errorName	errorDescription
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 'lat', 'lon' present in request?	400	Bad Request	Either 'lat' and 'lon' or 'x' and 'y' parameters should be present in request
Is 'x', 'y', present in request?	400	Bad Request	Either 'lat' and 'lon' or 'x' and 'y' parameters should be present in request
Is 'crs' present in request (when using parameters 'x' and 'y')?	400	Bad Request	EPSG parameter has to be defined
Is EPSG code correct in request?	400	Bad Request	Unknown coordinate system: EPSG:...
Is output format correct in request?	400	Bad Request	Incorrect output format(type) requested
Is language defined correctly in request?	400	Bad Request	Incorrectly defined language in request
Is region defined correctly in request?	501	Not Implemented	Unsupported region: '...'
Is rule set id defined correctly in request?	501	Not Implemented	Unsupported rule set id: '...'
Is radius defined correctly in request?	400	Bad Request	Incorrectly defined radius in request
Is limit defined correctly in request?	400	Bad Request	Incorrectly defined limit 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 coordinates - input `q` (Longitude, Latitude)
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.
distance	integer	no	Distance in meters between input coordinates and centroid of the output address
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 value: `Point`
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": "Longitude: 26.0, Latitude: 58.0",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "adob_type": "RB",
        "country": "EST",
        "extended_data": {
          "distance": 888,
          "crs": "EPSG:4326",
          "centroid": "26.014997,58.000471",
          "is_address": true
        },
        "level6": "Viru",
        "full_address": "Eesti, Valga maakond, Tõrva vald, Jõgeveste küla",
        "level1": "Valga maakond",
        "postal_code": "68616",
        "level3": "Jõgeveste küla",
        "level2": "Tõrva vald"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          26.014997,
          58.000471
        ]
      },
      "bbox": [
        26.014997,
        58.000471,
        26.014997,
        58.000471
      ]
    }
  ]
}

<?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>Longitude: 26.0, Latitude: 58.0</ns2:name>
    <ns2:Placemark>
      <xal:AddressDetails>
        <xal:AddressLines>
          <xal:AddressLine Type="full_address">Eesti, Valga maakond, Tõrva vald, Jõgeveste küla</xal:AddressLine>
          <xal:AddressLine Type="country">EST</xal:AddressLine>
          <xal:AddressLine Type="level1">Valga maakond</xal:AddressLine>
          <xal:AddressLine Type="level2">Tõrva vald</xal:AddressLine>
          <xal:AddressLine Type="level3">Jõgeveste küla</xal:AddressLine>
          <xal:AddressLine Type="level6">Viru</xal:AddressLine>
          <xal:AddressLine Type="postal_code">68616</xal:AddressLine>
          <xal:AddressLine Type="adob_type">RB</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.014997,58.000471,26.014997,58.000471</ns2:value>
        </ns2:Data>
        <ns2:Data name="centroid">
          <ns2:value>26.014997,58.000471</ns2:value>
        </ns2:Data>
        <ns2:Data name="crs">
          <ns2:value>EPSG:4326</ns2:value>
        </ns2:Data>
        <ns2:Data name="distance">
          <ns2:value>888</ns2:value>
        </ns2:Data>
      </ns2:ExtendedData>
      <ns2:Point>
        <ns2:coordinates>26.014997,58.000471</ns2:coordinates>
      </ns2:Point>
    </ns2:Placemark>
  </ns2:Document>
</ns2:kml>

Data sources and updates

Address data used in GDH Reverse 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.