Address components

Address component service (Gazetteer) is a tool for logical and mistake-free address search and saving. The unique address objects found can be saved to client's database with all necessary attributes and coordinates.

It's also possible to request address component lists by levels (e.g. all streets of a defined settlement unit).

Gazetteer is a combination of three APIs:

  • Address levels - service for level descriptions by countries.
  • Address lists by levels - service for requesting complete list of address components of a defined address node within a defined address level.
  • Unique address objects - Service for receiving full data of unique address objects.

More detailed descriptions of the forementioned APIs are given below.

Address levels

As the actual meaning of each address level differs by countries, it's possible to request a list of level descriptions by country.

The API can be also used for displaying level descriptions in address search component user interface.

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 address level descriptions from database Action API queries database with request parameters
Response message Message End Application creates response message according to "Response message" chapter

Sample request URI

https://api.geodatahub.eu/gz/levels/est?apikey=YOUR_API_KEY

Response examples by countries

<Map>
<LEVEL_0>COUNTRY_NAME</LEVEL_0>
<LEVEL_1>MUNICIPALITY</LEVEL_1>
<LEVEL_2>ADMINISTRATIVE_UNIT</LEVEL_2>
<LEVEL_3>SETTLEMENT_UNIT</LEVEL_3>
<LEVEL_4>SMALL_PLACE</LEVEL_4>
<LEVEL_5>STREET</LEVEL_5>
<LEVEL_6>HOUSE_NAME</LEVEL_6>
<LEVEL_6>LAND_UNIT_NAME</LEVEL_6>
<LEVEL_7>HOUSE_NUMBER</LEVEL_7>
</Map>
<Map>
<LEVEL_0>COUNTRY_NAME</LEVEL_0>
<LEVEL_1>MUNICIPALITY</LEVEL_1>
<LEVEL_2>TERRITORIAL_UNIT</LEVEL_2>
<LEVEL_3>SETTLEMENT_UNIT</LEVEL_3>
<LEVEL_4>STREET</LEVEL_4>
<LEVEL_5>HOUSE_NUMBER</LEVEL_5>
<LEVEL_5>HOUSE_NAME</LEVEL_5>
</Map>
<Map>
<LEVEL_0>COUNTRY_NAME</LEVEL_0>
<LEVEL_1>COUNTY</LEVEL_1>
<LEVEL_2>MUNICIPALITY</LEVEL_2>
<LEVEL_3>TERRITORIAL_UNIT</LEVEL_3>
<LEVEL_4>SETTLEMENT_UNIT</LEVEL_4>
<LEVEL_5>STREET</LEVEL_5>
<LEVEL_6>HOUSE_NAME</LEVEL_6>
<LEVEL_6>HOUSE_NUMBER</LEVEL_6>
</Map>

Address lists by levels

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 address level list from database Action API queries database with request parameters
Response message Message End Application creates response message according to "Response message" chapter

Sample request URI

https://api.geodatahub.eu/gz/6?l0=Eesti&l1=Tartu%20maakond&l2=Elva%20vald&l3=Käärdi%20alevik&apikey=YOUR_API_KEY

Relationships between levels

For each level there is a mandatory upper level that must be defined to request that level. For example:

  • In case of level0=Eesti, it is mandatory to define house number (level7) or house / land unit name (level6), to request Apartments level.
    House numbers (level7) can not be requested without defining either a street (level5) or a small place (level4) address node.

  • In case of level0= Latvija, to request level5 from level2, levels 3 and 4 must be null. In case either level3 or level4 is not null, the request must include at least one of them.

Unique address objects

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 address object information from database Action API queries database with request parameters
Response message Message End Application creates response message according to "Response message" chapter

Sample request URI

https://api.geodatahub.eu/gz/addr?l0=Eesti&l1=Tartu%20maakond&l2=Tartu%20linn&l5=Narva%20mnt&l7=123&apikey=YOUR_API_KEY

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 addr
  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 No 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.
    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.
  geometry - - -
    type string No Geometry type
    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

Data sources

POI data used in POI Service API are based on various sources according to the data provider.
Jāņa sēta data are based on Jāņa sēta POI database and OpenStreetMap contributors' data. Reach-U data are based on the OpenStreetMap contributors' data.