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
| 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
| 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
| 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. |
| 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 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.