How to Locate Addresses with the HERE Geocoder
In the previous article, we examined the output of a geocoding request. This article demonstrates multiple methods for address geocoding. The HERE Geocoder API provides global coverage where data is available. Geocoding results are calculated from point address databases and interpolated data from street networks.
The HERE geocoding API supports multiple methods for address geocoding based on a country’s addressing system. We’ll go case by case providing examples in Python.
Note: These examples assume you have an OAuth token to query the geocoder. The oauth token is part of the header in the HTTP GET request. See the Identity & Access Management Guide to learn more about using oauth with HERE services.
Street address geocoding
Geocoding by house number and street is the most common method of finding a location by an address. The following example returns the geocoding result for "1 Telegraph Hill, San Francisco, CA 94133", which is the Coit Tower, a landmark in San Francisco. The query is a free-form query and uses the “=q” parameter.
base_url = “https://geocode.search.hereapi.com/v1/geocode”
address = urllib.parse.quote_plus("1 Telegraph Hill, San Francisco, CA 94133")
url = (base_url+"?q="+address)
geocode = json.loads(requests.get(url, headers=headers).text)
print("Street address geocoding:")
pprint(geocode)
The geocoder returns the result as a geoJSON document. The result provides more than just the coordinates that support multiple use cases. The previous article defines each element in the result.
{'items': [{'access': [{'lat': 37.80266, 'lng': -122.40594}],
'address': {'city': 'San Francisco',
'countryCode': 'USA',
'countryName': 'United States',
'county': 'San Francisco',
'district': 'Telegraph Hill',
'houseNumber': '1',
'label': '1 Telegraph Hill Blvd, San Francisco, CA '
'94133-3106, United States',
'postalCode': '94133-3106',
'state': 'California',
'stateCode': 'CA',
'street': 'Telegraph Hill Blvd'},
'houseNumberType': 'PA',
'id': 'here:af:streetsection:uYm6skTu83XDOaI5FuOZpD:CggIBCD0nvTlAhABGgEx',
'mapView': {'east': -122.4048,
'north': 37.80356,
'south': 37.80176,
'west': -122.40708},
'position': {'lat': 37.80266, 'lng': -122.40594},
'resultType': 'houseNumber',
'scoring': {'fieldScore': {'city': 1.0,
'houseNumber': 1.0,
'postalCode': 1.0,
'state': 1.0,
'streets': [0.9]}, 'queryScore': 0.99},
'title': '1 Telegraph Hill Blvd, San Francisco, CA 94133-3106, '
'United States'}]}
Geocoding by house number and postal code
In countries where the postal code is only associated with a few addresses on the same street, it is possible to geocode an address with only the house number and postal code. It is a common practice in transport and parcel logistics.
This feature is available for Canada, the United Kingdom, the Netherlands, the United States of America (ZIP+4), Israel, Ireland, and Singapore. The `/geocode` endpoint supports this use case with qualified and freeform queries. The example demonstrates both types of queries.
# qualified query
house_number = "houseNumber=1"
postal_code = "postalCode=94133-3106"
country="country=USA"
base_url = “https://geocode.search.hereapi.com/v1/geocode”
url = (base_url +"?qq="+house_number+";"+postal_code)
geocode = json.loads(requests.get(url, headers=headers).text)
print("Qualified geocode by house numner and postal code)
# free form query
address = " 1 94133-3106"
base_url = “https://geocode.search.hereapi.com/v1/geocode
url = (base_url+"?q="+address)
geocode = json.loads(requests.get(url, headers=headers).text)
print("Free form geocode by house number and postal code)
pprint(geocode)
In either case, the geocoder API returns the address of Coit Tower.
Geocoding by postal code for Ireland and Singapore
The Irish national postcode system, Eircode, assigns a unique postal code for every home and business address. In Singapore, postal codes are also as precise as addresses. People can use the postal code to find a specific address and location in both countries - without a street name, city, neighborhood, or even house number. The geocoder can find a complete address with a postal code using a free-form or qualified query. This feature is available for these two countries only.
Ireland postal codes must use the seven-character Eircode. For example, the user can find an address of the Giant's Causeway at "44 Causeway Road, Bushmills, County Antrim, BT57 8SU" by specifying only the postal code - either as a qualified query or a free form query.
# Free form query
address = "BT57 8SU"
base_url = “https://geocode.search.hereapi.com/v1/geocode”
url = (base_url+"?q="+address)
geocode = json.loads(requests.get(url, headers=headers).text)
print("Address gecoding by Eircode with a free form query:\n\n")
pprint(geocode)
# Qualified query
address = "postalCode=BT57 8SU"
base_url = “https://geocode.search.hereapi.com/v1/geocode”
url = (base_url +"?qq="+address)
geocode = json.loads(requests.get(url, headers=headers).text)
print("Address gecoding by Eircode with a qualified query:\n\n")
pprint(geocode)
Either query returns the following. Note that the “localityType” is “postalCode” and the “resultType” is “locality.”
'items': [{'address': {'city': 'Bushmills',
'countryCode': 'GBR',
'countryName': 'United Kingdom',
'county': 'County Antrim',
'countyCode': 'ATM',
'label': 'BT57 8, Bushmills, Northern Ireland, United '
'Kingdom',
'postalCode': 'BT57 8',
'state': 'Northern Ireland'},
'id': 'here:cm:namedplace:22224736',
'localityType': 'postalCode',
'mapView': {'east': -6.38881,
'north': 55.25208,
'south': 55.14162,
'west': -6.6032},
'position': {'lat': 55.20478, 'lng': -6.5232},
'resultType': 'locality',
'scoring': {'fieldScore': {'postalCode': 0.95}, 'queryScore': 0.71},
'title': 'BT57 8, Bushmills, Northern Ireland, United Kingdom'}]}
Singapore postal codes consist of six digits. To ensure results from Singapore, provide either a spatial reference with an `at` parameter or with an `in` parameter with the Singapore country name or upper-case country code, "SGP." For example, to geocode the address "3 River Valley Rd, Singapore 179024", add the qualified field with the parameter “in=countryCode:SGP.”
# Address lookup by postal code in Singapore
address = "179024"
base_url = “https://geocode.search.hereapi.com/v1/geocode”
url = (base_url+"?q="+address+"&in=countryCode:SGP")
geocode = json.loads(requests.get(url, headers=headers).text)
print("Address gecoding by Singapore postal code:\n\n")
pprint(geocode)
The geocoding API returns a street address. Note that the “houseNumberType” is “PA” or Point Address and that the “resultType” is “houseNumber” because the Singapore postal code provides an exact location and address.
{'items': [{'access': [{'lat': 1.29129, 'lng': 103.84588}],
'address': {'building': 'Clarke Quay',
'city': 'Singapore',
'countryCode': 'SGP',
'countryName': 'Singapore',
'county': 'Singapore',
'district': 'Central Business District',
'houseNumber': '3E',
'label': 'Clarke Quay, 3E River Valley Rd, Singapore '
'179024, Singapore',
'postalCode': '179024',
'street': 'River Valley Rd'},
'houseNumberType': 'PA',
'id': 'here:af:streetsection:pSyqW--YhBZ8Pm7x2WgDHA:CgcIBCCH6YpyEAEaAjNFIgtDbGFya2UgUXVheQ',
'mapView': {'east': 103.84742,
'north': 1.29149,
'south': 1.28957,
'west': 103.8455},
'position': {'lat': 1.29053, 'lng': 103.84646},
'resultType': 'houseNumber',
'scoring': {'fieldScore': {'postalCode': 1.0}, 'queryScore': 1.0},
'title': 'Clarke Quay, 3E River Valley Rd, Singapore 179024, '
'Singapore'}]}
Area geocoding
The geocoder can also return coordinates for an area, such as city, district of a city, postal code, county, state, or country. The coordinates provide a routing destination for an area. Areas can be a 'well-known' street, a main railway station, or another significant road that allows autos. For example, a free-form text query returns geo-coordinates of San Francisco:
# Area geocoding for a city
address = urllib.parse.quote_plus("San Francisco")
base_url = “https://geocode.search.hereapi.com/v1/geocode”
url = (base_url+"?q="+address)
geocode = json.loads(requests.get(url, headers=headers).txt)
print("Address gecoding by area with a free form query:"
pprint(geocode)
The geocoder returns San Francisco as “city” for “localityType” and “resultType” as a “locality”.
{'items': [{'address': {'city': 'San Francisco',
'countryCode': 'USA',
'countryName': 'United States',
'county': 'San Francisco',
'label': 'San Francisco, CA, United States',
'postalCode': '94102',
'state': 'California',
'stateCode': 'CA'},
'id': 'here:cm:namedplace:21010233',
'localityType': 'city',
'mapView': {'east': -122.34945,
'north': 37.83214,
'south': 37.60402,
'west': -122.51429},
'position': {'lat': 37.77712, 'lng': -122.41964},
'resultType': 'locality',
'scoring': {'fieldScore': {'city': 1.0}, 'queryScore': 1.0},
'title': 'San Francisco, CA, United States'}]}
However, if we want to geocode San Francisco County, we can use a qualified query to return an administrative area. We add the `state` and `country` to get the exact response.
# Area geocoding for an administrative area
address = urllib.parse.quote_plus("county=San Francisco County;state=CA;country=USA")
base_url = “https://geocode.search.hereapi.com/v1/geocode”
url = (base_url+"?qq="+address)
geocode = json.loads(requests.get(url, headers=headers).text)
print("Address gecoding for an administrative area:\n\n")
pprint(geocode)
The geocoder responds to the request with the “resultType” as ”administrativeArea” and “administrativeAreaType” as “county.”
{'items': [{'address': {'countryCode': 'USA',
'countryName': 'United States',
'county': 'San Francisco',
'label': 'San Francisco, CA, United States',
'state': 'California',
'stateCode': 'CA'},
'administrativeAreaType': 'county',
'id': 'here:cm:namedplace:21010232',
'mapView': {'east': -122.28178,
'north': 37.92894,
'south': 37.69514,
'west': -123.01366},
'position': {'lat': 37.78228, 'lg': -122.41429},
'resultType': 'administrativeArea',
'scoring': {'fieldScore': {'country': 1.0,
'county': 1.0,
'state': 1.0},
'queryScore': 0.74},
'title': 'San Francisco, CA, United States'}]}
Place geocoding
The geocoder can return the coordinates of a known place. It supports geocoding business addresses, including business names, same as residential addresses.
For example, if we request a geocode for "Coit Tower," the API will return a list of places named "Coit." However, by adding a location reference such as "San Francisco," the geocoder will return the exact result. The example uses a free-form query, and the geocoder will parse the address to get the relevant results.
# Place geocoding
address = urllib.parse.quote_plus("Coit Tower San Francisco")
base_url = “https://geocode.search.hereapi.com/v1/geocode”
url = (base_url+"?q="+address)
geocode = json.loads(requests.get(url, headers=headers).text)
print("Address geocoding for a place with a qualified query:\n\n")
pprint(geocode)
The response consists of two results for the location of Coit Tower. Both “resultTypes” are “place,” but the first result has a “Bus Stop” as a category, which would be useful for routing. Note that this result lacks a “mapView. The second result has several entries for “categories” that label the result as either a “Tourist Attraction,” “Landmark-Attraction,” or a “Historical Monument.” We can use the categories to determine which result to use depending on the use case.
'items': [{'access': [{'lat': 37.80266, 'lng': -122.40594}],
'address': {'city': 'San Francisco',
'countryCode': 'USA',
'countryName': 'United States',
'county': 'San Francisco',
'district': 'Telegraph Hill',
'houseNumber': '1',
'label': 'Coit Tower, 1 Telegraph Hill Blvd, San '
'Francisco, CA 94133-3106, United States',
'postalCode': '94133-3106',
'state': 'California',
'stateCode': 'CA',
'street': 'Telegraph Hill Blvd'},
'categories': [{'id': '400-4100-0042',
'name': 'Bus Stop',
'primary': True}],
'id': 'here:pds:place:8409q8zn-0d9e4e4d5a3c482ba6bbbdd2a574b0d2',
'position': {'lat': 37.80266, 'lng': -122.40594},
'resultType': 'place',
'scoring': {'fieldScore': {'city': 1.0, 'placeName': 1.0},
'queryScore': 1.0},
'title': 'Coit Tower'},
{'access': [{'lat': 37.80266, 'lng': -122.40594}],
'address': {'city': 'San Francisco',
'countryCode': 'USA',
'countryName': 'United States',
'county': 'San Francisco',
'district': 'Telegraph Hill',
'houseNumber': '1',
'label': 'Coit Tower, 1 Telegraph Hill Blvd, San '
'Francisco, CA 94133-3106, United States',
'postalCode': '94133-3106',
'state': 'California',
'stateCode': 'CA',
'street': 'Telegraph Hill Blvd'},
'categories': [{'id': '300-3000-0023',
'name': 'Tourist Attraction',
'primary': True},
{'id': '300-3000-0000',
'name': 'Landmark-Attraction'},
{'id': '300-3000-0025',
'name': 'Historical Monument'}],
'id': 'here:pds:place:8409q8zn-cf21a8d50518480d9d0ddeb553a628ec',
'position': {'lat': 37.80266, 'lng': -122.40594},
'resultType': 'place',
'scoring': {'fieldScore': {'city': 1.0, 'placeName': 1.0},
'queryScore': 1.0},
'title': 'Coit Tower'}]}
Summary
The HERE geocoding API supports a variety of methods for retrieving coordinates from text input. An address can be a complete street address, a street name and number with a postal code, only a postal code in countries that support a unique code for a location such as Ireland or Singapore, an administrative area or locality, and a place such as a landmark. In addition, the geocoder accepts free form and structured input, which supports multiple use cases ranging from batch geocoding to form input validation.
For more information and example about HERE's geocoding API, visit the HERE Geocoding and Search API Guide.
Articles in the geocoding series:
Have your say
Sign up for our newsletter
Why sign up:
- Latest offers and discounts
- Tailored content delivered weekly
- Exclusive events
- One click to unsubscribe