Switching to LocationIQ’s Forward Geocoding API: A Practical Guide for Those Seeking Alternatives to HERE

So, you’re thinking of switching from HERE’s forward geocoding API to LocationIQ’s? You might be wondering what the differences are between the two services. Well, good news – we’ve got you covered!

In this blog post, we’re going to give you a comprehensive guide to help you through the transition process. First things first, the query URL and parameters are different between the two services. This means you’ll need to update your code to reflect the new URLs and parameters. Additionally, the output labels are also different, so you’ll need to adjust your code to work with the new labels.

But don’t worry, we’re here to help! We’ll provide you with examples of queries for both HERE and LocationIQ, so you can see the differences in action. We’ll also give you tips and best practices to make sure your transition goes smoothly. By the end of this post, you’ll have a clear understanding of the differences between HERE and LocationIQ, and you’ll be ready to make the switch. So, if you’re ready to take the next step in your geocoding journey, keep reading!

Differences in Query Parameters and URL Elements:

One of the first things you’ll need to do when transitioning from HERE’s geocoding API to LocationIQ’s is to understand the difference in the query URL. The query URL is the part of the API that you use to search for a specific location, and it’s essential to know how to use it correctly.

An example of forward geocoding API call with HERE:

https://geocode.search.hereapi.com/v1/geocode?q=200%20S%20Mathilda%20Sunnyvale%20CA&apiKey={YOUR_API_KEY}&in=countryCode:USA
&limit=1&lang=en-US

Query Parameters:

q (required): The query string to geocode.
in (optional): Search within a geographic area
limit (optional): The maximum number of results to return. The default value is 1.
lang (optional): The language in which to return the results.

URL Elements:

Base URL: https://geocode.search.hereapi.com/v1/geocode
Path: /v1/geocode
Parameters: ?q={query}&apiKey={api_key}&at={latitude},{longitude}&limit={limit}&lang={language}

On the other hand, LocationIQ’s forward geocoding API query URL looks like this:

https://us1.locationiq.com/v1/search.php?q=200%20S%20Mathilda%20Sunnyvale%20CA&key={YOUR_API_KEY}&countrycodes=US

Query Parameters:

q (required): The query string to geocode.
key (required): Your LocationIQ API Access Token.
format (optional): The format in which to return the results (json or xml).
countrycodes (optional): Limit search to a list of countries

URL Elements:

Base URL: https://us1.locationiq.com
Path: /v1/search?
Parameters: ?q={query}&key={access_token}&format={format}&countrycodes=ISO3166-2

Overall, both APIs have similar functionality and can be used to geocode addresses and locations. However, the specific query parameters and URL elements used by each API may differ. It’s important to consult the API documentation to ensure the right parameters are being used for your use case.

Type	HERE	LocationIQ
Base URL	`https://geocode.search.hereapi.com/v1/geocode`	`https://eu1.locationiq.com/v1/search.php`
Path	`/v1/geocode`	`/v1/search.php`
Query Parameters	`q`	`q`
Restrict Results to geography	`countryCode:{countryCode}[,{countryCode}]*`	`countrycodes, viewbox & bounded`
Language Parameter	`lang` parameter	`accept-language`

Differences in Output

Let’s take the example of “1600 Pennsylvania Ave NW, Washington, DC 20500”, which is the address of the White House. Here’s what the forward geocoding output looks like for HERE:

{
  "items": [
    {
      "title": "1600 Pennsylvania Ave NW, Washington, DC 20500, United States",
      "id": "here:af:streetsection:6Y3mKMJ0XV7.XnzJfymA:B",
      "resultType": "houseNumber",
      "houseNumberType": "PA",
      "address": {
        "label": "1600 Pennsylvania Ave NW, Washington, DC 20500, United States",
        "countryCode": "USA",
        "countryName": "United States",
        "state": "District of Columbia",
        "county": "District of Columbia",
        "city": "Washington",
        "district": "Northwest Washington",
        "street": "Pennsylvania Ave",
        "postalCode": "20500",
        "houseNumber": "1600"
      },
      "position": {
        "lat": 38.897676,
        "lng": -77.03653
      },
      "access": [
        {
          "lat": 38.89773,
          "lng": -77.03651
        }
      ],
      "mapView": {
        "west": -77.03802,
        "south": 38.8965,
        "east": -77.03503,
        "north": 38.89885
      },
      "scoring": {
        "queryScore": 1.0,
        "fieldScore": {
          "city": 1.0,
          "streets": [
            1.0
          ],
          "houseNumber": 1.0
        }
      }
    }
  ]
}

This response includes information such as the address, latitude and longitude, access points, and a map view. It also includes a scoring system that ranks the accuracy of the geocoding results.

This is how the same address output looks like for LocationIQ:

[
  {
    "place_id": "166200545",
    "licence": "https://locationiq.com/attribution",
    "osm_type": "way",
    "osm_id": "238241022",
    "boundingbox": [
      "38.8974908",
      "38.897911",
      "-77.0368537",
      "-77.0362519"
    ],
    "lat": "38.897699700000004",
    "lon": "-77.03655315",
    "display_name": "White House, 1600, Pennsylvania Avenue Northwest, Washington, District of Columbia, 20006, USA",
    "class": "office",
    "type": "government",
    "importance": 1.16472115416811
  }
]

When comparing the forward geocoding outputs from HERE and LocationIQ for the address “1600 Pennsylvania Ave NW, Washington, DC 20500” there are several key differences to note. Understanding these differences can help developers choose the best geocoding provider for their needs.

place_id/osm_id: Both HERE and LocationIQ provide unique identifiers for the location, but use different systems. HERE uses its own “id” parameter, while LocationIQ uses the OpenStreetMap among others. When response is from OpenStreetMap, results have the osm_type label.
licence: Both APIs provide information about the data license. HERE’s “licence” parameter provides a URL to the license information page, while LocationIQ’s “licence” parameter provides the license information itself.
osm_type: LocationIQ’s “osm_type” parameter indicates the type of the OSM element that the result belongs to (in this case, a “way” which represents a linear feature such as a street, path, or river). HERE does not provide this information.
boundingbox: Both APIs provide the latitude and longitude bounds for the location, but they use different formats. HERE’s “mapView” parameter provides the western, southern, eastern, and northern boundaries in a rectangular map view. LocationIQ’s “boundingbox” parameter provides the minimum and maximum latitude and longitude values for the location.
lat/position.lat: Both APIs provide the latitude of the location.
lon/position.lng: Both APIs provide the longitude of the location.
display_name/title: Both APIs provide a human-readable name for the location. HERE’s “title” parameter provides a concise name, while LocationIQ’s “display_name” parameter provides a more detailed name that includes the street address, city, state, postal code, and country.
class/resultType: HERE’s “resultType” parameter indicates the type of the location (in this case, a “houseNumber”). LocationIQ’s “class” parameter indicates the category of the location (in this case, an “office”).
type: Both APIs provide information about the type of location, but they use different systems. HERE’s “houseNumberType” parameter indicates the type of the house number (in this case, “PA” for Pennsylvania Avenue). LocationIQ’s “type” parameter indicates the type of the location itself (in this case, “government”).

Type of output	HERE’s parameter	LocationIQ’s parameter
Unique identifier	`id`	`osm_id`
Data license information	`licence` (URL)	`licence` (text)
Type of OSM element	N/A	`osm_type`
Latitude and longitude bounds	`mapView` (western, southern, eastern, and northern boundaries)	`boundingbox` (minimum and maximum latitude and longitude values)
Latitude	`position.lat`	`lat`
Longitude	`position.lng`	`lon`
Human-readable name	`title`	`display_name`
Type of location	`houseNumberType`	`type`
Category of location	`resultType`	`class`

Overall, while both HERE and LocationIQ provide accurate geocoding results, the output structure and labels differ slightly between the two providers. Developers should carefully review the output format of both providers and choose the one that best fits their needs. This may depend on factors such as the type of application, the level of precision required, and the specific parameters needed for each use case.

By understanding the differences between HERE and LocationIQ’s forward geocoding outputs, developers can make an informed decision and choose the best geocoding provider for their needs.

Best Practices:

When transitioning from one geocoding API to another, it is important to follow some best practices to ensure a smooth transition. Here are some best practices to consider:

Start by testing the new API on a small scale before integrating it into your application.
Ensure that the API you are switching to provides similar or better functionality than the one you are switching from.
Check the pricing and usage policy differences between the two APIs to make an informed decision.
Update your code and documentation to reflect the changes in the API.
If you are using a third-party library or SDK, make sure to update it or look for an alternative that supports the new API.

In conclusion, transitioning from HERE’s forward geocoding API to LocationIQ’s forward geocoding API requires updating your query URL, query parameters, and output labels. While both providers offer accurate geocoding results, the output structure and labels differ slightly between the two. When making the switch, it’s important to follow best practices such as testing the new API on a small scale, updating your code and documentation, and checking pricing and usage policy differences.

Why not give LocationIQ a try by signing up for a free account today? Simply fill out the form here and you can start exploring right away!