OpenStreetMap(Nominatim)

Nominatim (from the Latin, ‘by name’) is a tool to search OSM data by name and address and to generate synthetic addresses of OSM points (reverse geocoding). Using Geocoder you can retrieve OSM’s geocoded data from Nominatim.

Simple usage

OpenStreetMap does not require any keys for work. So you can begin without any setup.

import geocoder

g = geocoder.osm('New York city')
print(g.latlng)
# [40.7127281, -74.0060152]
print(g[0].latlng)
# Same as g.latlng: [40.7127281, -74.0060152]

This provider may return multiple results by setting the parameter max_results to the desired number. By default, 1 entry retrieved. Multiple results contained as internal sequence. You can check any result, by direct member object calling like in normal lists. Without member number mention, object with index 0 is always called.

import geocoder

g = geocoder.osm('New York city', max_results=3)
print(g[0].latlng)
# [40.7127281, -74.0060152]
print(g.latlng)
# Same as g[0].latlng: [40.7127281, -74.0060152]
print(g[1].latlng)
# Other result: [40.75126905, -73.98482021795536]

Custom or Local Nominatim Server

Setting up your own local offline Nominatim server is possible, using the following the Nominatim Install instructions. This enables you to request as much geocoding as your need.

Also, usage of any custom Nominatim Server is possible with setting url parameter. url should point to direct /search endpoint, check example below.

import geocoder

g = geocoder.osm("New York City", url="http://localhost/nominatim/search")
print(g[0].latlng)
# [40.7127281, -74.0060152]

OSM Addresses

The [addr tag] is the prefix for several addr:* keys to describe addresses.

This format is meant to be saved as a CSV and imported into JOSM.

import geocoder
g = geocoder.osm('11 Wall Street, New York')
print(g.osm)
# {
#     "x": -74.010865,
#     "y": 40.7071407,
#     "addr:country": "United States of America",
#     "addr:state": "New York",
#     "addr:housenumber": "11",
#     "addr:postal": "10005",
#     "addr:city": "NYC",
#     "addr:street": "Wall Street"
# }

Command Line Interface

geocode 'New York city' --provider osm --out geojson | jq .
geocode 'New York city' -p osm -o osm
geocode 'New York city' -p osm --url localhost

Helper method parameters

Helper method is recommended way to use providers, if no class extension required. During project modification this public API will be last thing for non-compatible changes.

geocoder.osm(query, method='geocode', **kwargs)[source]

OSM Provider

Provider supported methods:

geocode
details
reverse

Parameters

query – Your search location you want geocoded.
method – One of provider’s supported methods, defaults to geocode.
url – Custom OSM Server URL location (ex: http://nominatim.openstreetmap.org/search)

Working class API

class geocoder.providers.OsmQuery(location, url=None, key=None, timeout=None, proxies=None, session=None, headers=None, params=None, **kwargs)[source]

Bases: geocoder.base.MultipleResultsQuery

Nominatim API Reference: https://nominatim.org/release-docs/develop/api/Overview/

add(value)

Special method implementation for custom MutableSequence subclass

Not expected to be nested or changed in subclasses.

append(value): S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

debug(): Display debug information for instance of MultipleResultsQuery

extend(values): S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, value)

Special method implementation for custom MutableSequence subclass

Not expected to be nested or changed in subclasses.

pop([index]) → item -- remove and return item at index (default last).: Raise IndexError if list is empty or index is out of range.

rate_limited_get(url, **kwargs): By default, simply wraps a requests.get() request

remove(value): S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse(): S.reverse() – reverse IN PLACE

property geojson: Output all answers as GeoJSON FeatureCollection

property has_data

Status of geocoding if request was made

Raises: RuntimeError – When external request was not made before property call

property status

Specify current summary status of instance

Possible statuses:

“External request was not made”
“OK” - when request was made, and any result retrieved
requests error text representation, if request faced error
“ERROR - No results found”
“ERROR - Unhandled Exception”

Returned object properties

class geocoder.providers.OsmResult(json_content)[source]

Bases: geocoder.base.OneResult

debug(): Display debug information for instance of OneResult

property accuracy

property address: Full comma-separated address

property allotments

place=allotments

Dacha or cottage settlement, which is located outside other inhabited locality. This value is used mainly in Russia and other countries of the former Soviet Union, where a lot of such unofficial settlements exist

property bbox: Output answer as GeoJSON bbox if it can be calculated/retrieved.

property bounds: Output answer as Google Maps API bounds if it can be calculated/retrieved.

property city

place=city

The largest urban settlements in the territory, normally including the national, state and provincial capitals. These are defined by charter or other governmental designation in some territories and are a matter of judgement in others. Should normally have a population of at least 100,000 people and be larger than nearby towns.

See place=suburb and place=neighbourhood on how to tag divisions within a city. The outskirts of urban settlements may or may not match the administratively declared boundary of the city.

property confidence: Is as a measure of how confident we are that centre point coordinates returned for the result precisely reflect the result.

property country: admin_level=2

property country_code: admin_level=2

property county: admin_level=6

property district: admin_level=5/6

property east: Return optional east coordinate of bbox, if available.

property farm

place=farm

A farm that has its own name. If the farm is not a part of bigger settlement use place=isolated_dwelling. See also landuse=farmyard

property geojson: Output answer as GeoJSON Feature

property geometry: Output answer as GeoJSON Point

property hamlet

place=hamlet

A smaller rural community typically with less than 100-200 inhabitants, few infrastructure.

property house_number

property icon

property importance

property island

place=island

Identifies the coastline of an island (> 1 km2), also consider place=islet for very small islandsIdentifies the coastline of an island (> 1 km2), also consider place=islet for very small islands

property isolated_dwelling

place=isolated_dwelling

Smallest kind of human settlement. No more than 2 households.

property lat: Latitude of the object

property latlng: Optional list of latitude and longitude values.

property license

property lng: Longitude of the object

property locality

place=isolated_dwelling

For an unpopulated named place.

property municipality: admin_level=8

property neighborhood

place=neighborhood

A named part of a place=village, a place=town or a place=city. Smaller than place=suburb and place=quarter.

The tag can be used for any kind of landuse or mix of landuse (such as residential, commercial, industrial etc). Usage of this term depends greatly on local history, culture, politics, economy and organization of settlements. More specific rules are intentionally avoided.

Note: the British English spelling is used rather than the: American English spelling of neighborhood.

property north: Return optional north coordinate of bbox, if available.

property northeast: Return north-east list of coordinates for bounds, if available.

property ok

Status of retrieving location/IP coordinates or reverse geocoding.

Usually should be replaced in reverse results class.

property osm_id

property osm_type

property place_id

property place_rank

property population

property postal

property quality

property quarter

place=quarter

A named part of a bigger settlement where this part is smaller than a suburb and bigger than a neighbourhood. This does not have to be an administrative entity.

The term quarter is sometimes used synonymously for neighbourhood.

property region: admin_level=3

property south: Return optional south coordinate of bbox, if available.

property southwest: Return south-west list of coordinates for bounds, if available.

property state: admin_level=4

property status: Specify current summary status of instance

property street

property suburb

place=suburb

A distinct section of an urban settlement (city, town, etc.) with its own name and identity. e.g.

annexed towns or villages which were formerly independent,
independent (or dependent) municipalities within a city or next to a much bigger town
historical districts of settlements
industrial districts or recreation areas within a settlements with specific names.

property town

place=town

A second tier urban settlement of local importance, often with a population of 10,000 people and good range of local facilities including schools, medical facilities etc and traditionally a market. In areas of low population, towns may have significantly lower populations.

See place=neighbourhood and possibly also place=suburb on how to tag divisions within a town.

property type

property village

place=village

A smaller distinct settlement, smaller than a town with few facilities available with people traveling to nearby towns to access these. Populations of villages vary widely in different territories but will nearly always be less than 10,000 people, often a lot less.

See place=neighbourhood on how to tag divisions within a larger village

property west: Return optional west coordinate of bbox, if available.

property wkt: Output coordinates in well-known text format, no SRID data.

property x: Longitude of the object

property xy: Optional list of longitude and latitude values.

property y: Latitude of the object