Skip to content

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 instance-attribute 🔗

The placex table is the main source for result usually containing OSM data.

OSMLINE = 2 class-attribute instance-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 instance-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 instance-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 instance-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] instance-attribute 🔗

Main category of the place, described by a key-value pair.

names: Dict[str, str] instance-attribute 🔗

All available names for the place including references, alternative names and translations.

fromarea: bool instance-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 instance-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 instance-attribute 🔗

Address rank of the place.

distance: float instance-attribute 🔗

Distance in degrees between the result place and this address part.

place_id: Optional[int] = None class-attribute instance-attribute 🔗

Internal ID of the place.

osm_object: Optional[Tuple[str, int]] = None class-attribute instance-attribute 🔗

OSM type and ID of the place, if such an object exists.

extratags: Optional[Dict[str, str]] = None class-attribute instance-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 instance-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 instance-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.

Each entry in the list of search terms contains the following detailed information.

word: Optional[str] = None class-attribute instance-attribute 🔗

Untransliterated form, if available.

word_id: int instance-attribute 🔗

Internal identifier for the word.

word_token: str instance-attribute 🔗

Normalised and transliterated form of the word. This form is used for searching.

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.