Characteristic
Short description
An address is a specification of the number of the house, name of the road, number of the postal code and name of the city where a person lives or works, and where letters can be sent. An address can consist of the following elements:
- Country
- State
- Province
- Postal code
- City
- District
- Subdistrict
- Street
- House number
Detailed Consideration
Knowing what to enter or expect in the different fields helps you to achieve good geocoding results. In this section you get all information about the structure of the xLocate address system.
Components of an address
| Explanation | Request/Response | |
|---|---|---|
| Country | Countries can be identified by name, ISO code or country code plate. The definition what belongs to a country in a map may depend on the data provider. | When using the SearchByAddressRequest,
Country has its own input field. When using the SearchByTextRequest, all inputs are given in the same field. |
| State | The State describes the first-level subdivision of a country (where applicable). This subdivision may have a different name in a given country, such as province, canton, territory, or department. The term State is used independently of this domestic terminology. | When using the SearchByAddressRequest,
State has its own input field. When using the SearchByTextRequest, all inputs are given in the same field. |
| Province | The Province describes the second-level subdivision of a country (where applicable). This subdivision may have a different name in a given country, such as county, district or region. The term Province is used independently of this domestic terminology. | When using the SearchByAddressRequest,
Province has its own input field. When using the SearchByTextRequest, all inputs are given in the same field. |
| Postal Code | A postal code (or zip-code) is used by a country's postal authority to identify where an address is located. | When using the SearchByAddressRequest,
postal code has its own input field. When using the SearchByTextRequest, all inputs are given in the same field. |
| City | The term City means an inhabited place of greater size, population, or importance compared to smaller entities at communal level like urban districts. | When using the SearchByAddressRequest,
all components of a locality (city, district and subdistrict) can be spread over the City, District and Subdistrict input fields. When using the SearchByTextRequest, all inputs are given in the same field. In the response, the City field will contain only the most relevant locality name, any other names like administrative hierachies below state e.g. county, region etc. are returned in separate address fields. |
| District | The term District means an entity at a lower level in the communal hierarchy compared to City. It is used as a general term for names of urban districts and suburbs. | When using the SearchByAddressRequest,
all components of a locality (city, district and subdistrict) can be spread over the City, District and Subdistrict input fields. When using the SearchByTextRequest, all inputs are given in the same field. In the response, the District field will contain the communal entity one level below the City field. |
| Subdistrict | The term Subdistrict means an entity at another lower level in the communal hierarchy compared to District. It is used as a general term for names of places or neighbourhoods. | When using the SearchByAddressRequest,
all components of a locality (city, district and subdistrict) can be spread over the City, District and Subdistrict input fields. When using the SearchByTextRequest, all inputs are given in the same field. In the response, the Subdistrict field will contain the communal entity one level below the District field. |
| Street | Is the name of the road where an address is located. | When using the SearchByAddressRequest,
street name and house number can be entered in the street input field together. When using the SearchByTextRequest, all inputs are given in the same field. |
| House Number | Is the number of the house where an address is located. | When using the SearchByAddressRequest,
house number has its own input field. When using the SearchByTextRequest, all inputs are given in the same field. |
Good to know
Additional address information
In some countries, and for some special use cases, some additional information may be helpful e.g.:
- P.O. box number
- appartment number
- floor
- trade fair booth numbers
This data is currently not available to xLocate, so it cannot be returned or searched for. It is best to keep this information in separate fields, which are not passed to the geocoding. This approach prevents overwriting this extra information and helps to reach a high geocoding quality.
Communal hierachies
When the fields City, District and Subdistrict are used as input fields, it is not obvious for the end-user to insert individual words at the right place according the preexisting communal hierachies. Therefore, the content of all of these fields are combined to one single collection. This collection is used in the subsequent search which figures out the mapping of the several communal levels by itself.
Related Topics
| Showcase | Search addresses |
| Integration Sample | Searching free-form address input |
| Integration Sample | Searching structured address input |