Result handling
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.
Result fields
Sources
Nominatim takes the result data from multiple sources. The source_table field
in the result describes, from which source the result was retrieved.
The SourceTable type lists the possible sources a result can have.
PLACEX = 1
class-attribute
The placex table is the main source for result usually containing OSM data.
OSMLINE = 2
class-attribute
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
class-attribute
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
class-attribute
The postcode table contains artificial centroids for postcodes, computed from the postcodes available with address points. Results are always approximate.
COUNTRY = 5
class-attribute
The country table provides a fallback, when country data is missing in the OSM data.
Detailed address description
When the 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
list of 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.
The 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.
category: Tuple[str, str]
class-attribute
Main category of the place, described by a key-value pair.
names: Dict[str, str]
class-attribute
All available names for the place including references, alternative names and translations.
fromarea: bool
class-attribute
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.
isaddress: bool
class-attribute
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.
rank_address: int
class-attribute
Address rank of the place.
distance: float
class-attribute
Distance in degrees between the result place and this address part.
place_id: Optional[int] = None
class-attribute
Internal ID of the place.
osm_object: Optional[Tuple[str, int]] = None
class-attribute
OSM type and ID of the place, if such an object exists.
extratags: Optional[Dict[str, str]] = None
class-attribute
Any extra information available about the place. This is a dictionary that usually contains OSM tag key-value pairs.
admin_level: Optional[int] = None
class-attribute
The administrative level of a boundary as tagged in the input data. This field is only meaningful for places of the category (boundary, administrative).
local_name: Optional[str] = None
class-attribute
Place holder for localization of this address part. See Localization below.
Detailed search terms
The 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
its address.
Localization
Results are always returned with the full list of available names.
Locale
Helper class for localization of names.
It takes a list of language prefixes in their order of preferred usage.
display_name(names)
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.
from_accept_languages(langstr)
staticmethod
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.