The search functions of the Nominatim API always return a result object with the raw information about the place that is available in the database. This section discusses data types used in the results and utility functions that allow further processing of the results.
Nominatim takes the result data from multiple sources. The
in the result describes, from which source the result was retrieved.
SourceTable type lists the possible sources a result can have.
PLACEX = 1
The placex table is the main source for result usually containing OSM data.
OSMLINE = 2
The osmline table contains address interpolations from OSM data. Interpolation addresses are always approximate. The OSM id in the result refers to the OSM way with the interpolation line object.
TIGER = 3
TIGER address data contains US addresses imported on the side, see Installing TIGER data. TIGER address are also interpolations. The addresses always refer to a street from OSM data. The OSM id in the result refers to that street.
POSTCODE = 4
The postcode table contains artificial centroids for postcodes, computed from the postcodes available with address points. Results are always approximate.
COUNTRY = 5
The country table provides a fallback, when country data is missing in the OSM data.
Detailed address description
address_details parameter is set, then functions return not
only information about the result place but also about the place that
make up the address. This information is almost always required when you
want to present the user with a human-readable description of the result.
See also Localization below.
The address details are available in the
address_rows field as a ordered
AddressLine objects with the country information last. The list also
contains the result place itself and some artificial entries, for example,
for the house number or the country code. This makes processing and creating
a full address easier.
AddressLine may contain the following fields about a related place
and its function as an address object. Most fields are optional.
Their presence depends on the kind and function of the address part.
Internal ID of the place.
osm_object: Optional[Tuple[str, int]]
OSM type and ID of the place, if such an object exists.
category: Tuple[str, str]
Main category of the place, described by a key-value pair.
names: Dict[str, str]
All available names for the place including references, alternative names and translations.
extratags: Optional[Dict[str, str]]
Any extra information available about the place. This is a dictionary that usually contains OSM tag key-value pairs.
The administrative level of a boundary as tagged in the input data. This field is only meaningful for places of the category (boundary, administrative).
If true, then the exact area of the place is known. Without area information, Nominatim has to make an educated guess if an address belongs to one place or another.
If true, this place should be considered for the final address display. Nominatim will sometimes include more than one candidate for the address in the list when it cannot reliably determine where the place belongs. It will consider names of all candidates when searching but when displaying the result, only the most likely candidate should be shown.
Distance in degrees between the result place and this address part.
Detailed search terms
details function can return detailed information about which search terms
may be used to find a place, when the
keywords parameter is set. Search
terms are split into terms for the name of the place and search terms for
Each entry in the list of search terms contains the following detailed information.
Results are always returned with the full list of available names.
Helper class for localization of names.
It takes a list of language prefixes in their order of preferred usage.
Return the best matching name from a dictionary of names containing different name variants.
If 'names' is null or empty, an empty string is returned. If no appropriate localization is found, the first name is returned.
Create a localization object from a language list in the format of HTTP accept-languages header.
The functions tries to be forgiving of format errors by first splitting the string into comma-separated parts and then parsing each description separately. Badly formatted parts are then ignored.