Beyond Basic Address Geocoding
Addresses are labels that simplify the varied and complex ways we locate businesses, homes, landmarks, cities, and administrative areas such as cities or other political subdivisions. Basic geocoders return only coordinates that are derived from point databases or are interpolated from street number ranges from a road network.
The HERE geocoder API is a global geocoding service that returns coordinates and more. It performs the heavy lifting of parsing addresses or location references and determining the applicable data to return geo-coordinates to locate a place. This article shows how to send a query to the API and explains the data returned for a request.
Querying the geocoder API
Use an HTTP GET request to call the HERE geocoder API. The geocoder accepts two types of queries, a free from query and a qualified query. The free form query is a text string and the geocoder will parse it accordingly. A free from query uses “=q” as the query parameter
GET https://geocode.search.hereapi.com/v1/geocode?q=1+Telegraph+Hill%2C+San+Francisco%2C+CA+94133
The API also accepts qualified queries, which is useful when the address comes from a form or structured input. A qualified query uses “=qq” as the query parameter.
GET https://geocode.search.hereapi.com/v1/geocode?
qq=
houseNumber=1;
street=Telegraph+Hill;
city=San+Francisco;
state=CA;
postalCode=94133;
country=United+States
A qualified query can accept the house number and street name as a single input, e.g.:
GET https://geocode.search.hereapi.com/v1/geocode?
qq=
street=1+Telegraph+Hill;
city=San+Francisco;
state=CA;
postalCode=94133;
country=United+States
You can also combine a free form and qualified query to form a hybrid query:
GET https://geocode.search.hereapi.com/v1/geocode?
q=1+Telegraph+Hill
&qq=postalCode=94133
Free form, qualified, and hybrid queries provide a range of options for submitting address to the geocoder. When to use a query type depends on the use case. For example, geocoding a list of addresses from a file would apply to a free-form query, and structured input from a form could use a qualified or hybrid query.
Address Geocoding Results
Unlike a basic geocoder, the HERE geocoding API returns a JSON document that is more than a simple coordinate pair. There are many elements in the JSON that support many use cases ranging from address correction and mailing addresses to geographic elements to drive routing or displaying a map. Let's take a look at the different parts of the document.
- The access element is the access point (or navigation coordinates) locates the point to start or end a drive.
'access': [{'lat': 37.80266, 'lng': -122.40594}] - Address geocoder can clean and normalize an address and return it in a well-structured format. For example, the address omits the street suffix and provides a 5 digit zip code. Note that the address geocoder returns the country code and name, ZIP+4, and adds the street suffix. In addition, the geocoding API returns a standardized address suitable for mailing purposes.
'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'}, - The houseNumberType is the method of geocoding. The responses are “PA” for Point Address and “Interpolated” for a position based on street address range.
'houseNumberType': 'PA', - The geocoder also returns a 'mapView' which is a bounding box for the address and can be used to set the view in a mapping application.
'mapView': {'east': -122.4048,d 'north': 37.80356, 'south': 37.80176, 'west': -122.40708}, - In the case of point addresses, a position can be the rooftop point, a point close to the building entry, a point close to the building or driveway, or a parking lot that belongs to the building.
'position': {'lat': 37.80266, 'lng': -122.40594}, - The geocoding API provides a score for the quality of the geocode. The overall, or queryScore, is 0.99 because the address did not include the street suffix.
'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},Even if the address is incorrect, e.g., “1 Telephone Hill, San Francisco, CA 94133”, the geocoder API provides a score to evaluate the results. The coordinates of both geocoded addresses (Telegraph Hill vs. Telephone Hill) are the same despite the incorrect street name.
'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.51]}, 'queryScore': 0.85},
Conclusion
The HERE geocoder API does the heavy lifting at both the front end by accepting multiple ways of input and parsing it appropriately. On the back end, the API returns a detailed JSON response that serves many use cases such as address correction, mail label generation, and start and end points for routing.
The primary function of geocoding is to locate an address or location reference and provide coordinates. The HERE geocoder provides coordinates of a rooftop or a point close to the entry or driveway of a building. In addition, it provides bounding box coordinates to zoom to the address for web mapping applications. Incorrect addresses are not uncommon, whether it’s a misspelling or a missing or wrong street suffix, the geocoder API will make a best effort to locate an address and provide individual scores for address parts and an overall score. You can use this information to accept or reject a location based on a threshold for an acceptable score. You can accept or reject a geocode programmatically because it is in the JSON document.
There’s a lot more to geocoding beyond returning coordinates. Learn more about HERE’s geocoding API with the HERE Geocoding & Search API User Guide and the API Reference.
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