Making the Switch: A Developer’s Guide to Migrating from HERE to LocationIQ’s Autocomplete API

Are you considering a move from HERE’s Autocomplete API to LocationIQ’s Autocomplete API? It’s natural to have questions about the differences between the two services. Fortunately, we’ve got you covered with a comprehensive guide to help you make the transition. One of the first things to note is that the query URL and parameters are different between the two services, meaning you’ll need to update your code. Additionally, output labels also differ, requiring code adjustments. Don’t worry though; we’ll provide you with examples of queries for both services, along with tips and best practices to ensure a smooth transition.

By the end of this post, you’ll have a clear understanding of the differences between HERE and LocationIQ and be ready to make the switch. So, if you’re ready to advance your geocoding journey, let’s dive in!

Differences in Query Parameters and URL Elements:

To successfully switch from HERE’s autocomplete API to LocationIQ’s, one of the initial steps is to understand the variation in the query URL. The query URL is a fundamental component of the API that is utilized to autocomplete for a particular location, and it’s crucial to grasp its correct usage.

Here’s an example of how to use the Autocomplete API to suggest completions for the query string “Empir” near New York City:

https://autocomplete.search.hereapi.com/v1/autocomplete?q=Empir&apiKey={your_api_key}&at=40.7831,-73.9712

HERE’s Query Parameters

The Autocomplete API supports the following query parameters:

• q (required): The partial query string to autocomplete.
• apiKey (required): Your HERE API key.
• at (optional): The geographic location to use as a basis for the search. This can be specified as a latitude/longitude pair, or as a string representing a location.
• in (optional): The geographic area to restrict the search to. This can be specified as a bounding box or as a circle around a central point.
• lang (optional): The language in which to return the results.

In this example, we use the q parameter to specify the partial query string “Empir”, the apiKey parameter to specify our API key, and the at parameter to specify the location around which to search for results (in this case, the latitude and longitude of New York City).

The API will return a JSON response that contains an array of autocomplete suggestions. Each suggestion will contain a title field with the suggested completion, as well as other optional fields such as category, highlightedTitle, and distance.

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

https://api.locationiq.com/v1/autocomplete?key=YOUR_API_KEY&q=Empir&countrycodes=US

LocationIQ’s Autocomplete Query Parameters:

• key (Required): The API key to authenticate the request.
• q (Required): The user query string to search for.
• limit (Optional): The maximum number of suggestions to return.
• viewbox (Optional): The bounding box to bias results towards in the format of south-west longitude, south-west latitude, north-east longitude, north-east latitude.
• bounded (Optional): Whether or not to limit results to the bounding box specified in the viewbox parameter. Default is 1 (limit results).
• accept-language (Optional): The language of the suggested terms. Default is en.
• countrycodes (Optional): Limit search to a list of countries

Both APIs have their own strengths and may be more suitable for different use cases. It’s important to review the documentation of each API to ensure that the query parameters and URL elements are used correctly.

Function	HERE Parameter	LocationIQ Parameter
API Key	apiKey	key
User Query	q	q
Search Context	at	viewbox
Maximum Suggestions	limit	limit
Language	lang	accept-language
Restrict results to a country	in	countrycodes

Differences in Output

Here is an example API response from HERE’s autocomplete for the query “white” with a country filter for the United States and a limit of 3 results:

{
  "suggestions": [
    {
      "label": "White House, 1600 Pennsylvania Ave NW, Washington, DC, United States",
      "language": "en",
      "countryCode": "USA",
      "locationId": "NT_w0zObJyrm3qonxbIj.zM0B",
      "address": {
        "country": "United States",
        "state": "District of Columbia",
        "county": "District of Columbia",
        "city": "Washington",
        "district": "Downtown-Penn Quarter-Chinatown",
        "postalCode": "20500",
        "street": "1600 Pennsylvania Ave NW",
        "houseNumber": "1600"
      },
      "matchLevel": "street"
    },
    {
      "label": "White River Amphitheatre, Southeast 408th Street, Auburn, WA, United States",
      "language": "en",
      "countryCode": "USA",
      "locationId": "NT_3h0uB1JNcgX9DuBn04oFDB",
      "address": {
        "country": "United States",
        "state": "Washington",
        "county": "King",
        "city": "Auburn",
        "district": "Auburn",
        "postalCode": "98092",
        "street": "Southeast 408th Street"
      },
      "matchLevel": "street"
    },
    {
      "label": "White Castle, South Broadway, White Plains, NY, United States",
      "language": "en",
      "countryCode": "USA",
      "locationId": "NT_BABojaKl9bjyn8xWVsR5JD",
      "address": {
        "country": "United States",
        "state": "New York",
        "county": "Westchester",
        "city": "White Plains",
        "district": "White Plains",
        "postalCode": "10601",
        "street": "South Broadway"
      },
      "matchLevel": "street"
    }
  ]
}

In this response, HERE’s autocomplete API returned 3 items that match the query “white” in the United States.

Let’s take a look at LocationIQ’s Autocomplete API response for the query “white” in United States limited to 3 results

[
  {
    "place_id": "321781685615",
    "osm_id": "238241022",
    "osm_type": "way",
    "licence": "https://locationiq.com/attribution",
    "lat": "38.8976997",
    "lon": "-77.03655315",
    "boundingbox": [
      "38.8974908",
      "38.897911",
      "-77.0368537",
      "-77.0362519"
    ],
    "class": "office",
    "type": "government",
    "display_name": "White House, 1600, Pennsylvania Avenue Northwest, Washington, District of Columbia, 20006, USA",
    "display_place": "White House",
    "display_address": "1600, Pennsylvania Avenue Northwest, Washington, District of Columbia, 20006, USA",
    "address": {
      "name": "White House",
      "house_number": "1600",
      "road": "Pennsylvania Avenue Northwest",
      "city": "Washington",
      "state": "District of Columbia",
      "postcode": "20006",
      "country": "United States of America",
      "country_code": "us"
    }
  },
  {
    "place_id": "322014230782",
    "osm_id": "1800962",
    "osm_type": "relation",
    "licence": "https://locationiq.com/attribution",
    "lat": "38.0632329",
    "lon": "-88.1577725",
    "boundingbox": [
      "37.8834123",
      "38.261436",
      "-88.3745284",
      "-87.91494"
    ],
    "class": "place",
    "type": "county",
    "display_name": "White County, Illinois, USA",
    "display_place": "White County",
    "display_address": "Illinois, USA",
    "address": {
      "name": "White County",
      "state": "Illinois",
      "country": "United States of America",
      "country_code": "us"
    }
  },
  {
    "place_id": "321735600189",
    "osm_id": "1074327",
    "osm_type": "relation",
    "licence": "https://locationiq.com/attribution",
    "lat": "34.6322605",
    "lon": "-83.7596041",
    "boundingbox": [
      "34.503593",
      "34.8013746",
      "-83.87735",
      "-83.6155902"
    ],
    "class": "place",
    "type": "county",
    "display_name": "White County, Georgia, USA",
    "display_place": "White County",
    "display_address": "Georgia, USA",
    "address": {
      "name": "White County",
      "state": "Georgia",
      "country": "United States of America",
      "country_code": "us"
    }
  }
]

The main difference between HERE’s and LocationIQ’s autocomplete responses is the structure and content of the output.

• suggestions vs []: The main difference between HERE’s and LocationIQ’s autocomplete API response is the top-level key for the response data. HERE uses the suggestions key to hold an array of suggested locations, while LocationIQ simply returns an array of locations.
• label vs display_name: The suggested location in HERE’s response is held in the label key, while in LocationIQ’s response, it’s in the display_name key. Both of these keys hold a human-readable name for the suggested location.
• matchLevel: Both APIs provide a matchLevel key to indicate how well the suggested location matches the user’s input. HERE uses a set of possible match levels (e.g., “city”, “street”, “pointAddress”) to indicate the level of granularity for the suggested location, while LocationIQ simply provides a string value indicating the “match quality” of the result.
• locationId vs osm_id + osm_type: In HERE’s response, each suggested location has a unique locationId value, while in LocationIQ’s response, the corresponding value is osm_id and osm_type. Both of these keys hold an ID that can be used to look up more information about the suggested location.
• address vs address: Both APIs provide an address key to hold more detailed information about the suggested location, such as the street address, city, state/province, and postal code. The structure of this object is slightly different between the two APIs, but the data is similar.
• countryCode vs address.country_code: HERE includes a countryCode key to indicate the two-letter country code for the suggested location, while LocationIQ provides the same information in address.country_code.

Type of output	HERE’s parameter	LocationIQ’s parameter
Address	label	display_name
Country code	countryCode	address.country_code
Location ID	locationId	osm_id & osm_type
House number	address.houseNumber	address.house_number
Road/street	address.street	address.road
City/town	address.city	address.city
County	address.county	address.county
State/province	address.state	address.state
Postal code	address.postalCode	address.postcode

Overall, the specific differences between the output of HERE and LocationIQ will depend on the specific query and the properties of the location being queried. However, both services aim to provide accurate and useful information about a location, and the differences between their outputs may reflect differences in their underlying data sources or algorithms.

Best Practices:

When transitioning from one Autocomplete 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.

To conclude, when shifting from HERE’s autocomplete API or LocationIQ’s autocomplete API, developers need to adjust their query URL, query parameters, and output labels. While both services yield accurate outcomes, the output formation and labels may be dissimilar. It is crucial to abide by best practices, such as testing the fresh API in a small-scale, amending code and documents, and scrutinizing rates and usage policy discrepancies when effecting the transition.

Now, it’s time for you to take the next step — sign up for LocationIQ’s Autocomplete API. Join the growing community of developers & businesses who have made the switch. Dive in now and discover the power of LocationIQ!