LocationIQ Getting Started: API Key & First Request (2026)

Getting started overview

Getting started with LocationIQ involves a series of steps designed to enable developers to quickly integrate its mapping and geospatial services into their applications. The primary goal is to obtain an API key and successfully execute a first API call, verifying the setup. LocationIQ provides services such as geocoding, reverse geocoding, and routing, built upon OpenStreetMap data LocationIQ documentation overview. The platform offers a free tier, allowing for initial development and testing without immediate financial commitment LocationIQ pricing page.

The typical workflow includes account registration, API key generation, and making an authenticated HTTP request to one of LocationIQ's API endpoints. This guide focuses on these initial steps, providing practical instructions and code examples to facilitate a rapid setup.

Quick Reference: LocationIQ Getting Started Steps

Create an account and get keys

To access LocationIQ's services, you must first create an account and obtain an API key. This key authenticates your requests and links them to your usage plan. LocationIQ provides a free tier that includes 5,000 requests per day, suitable for initial development and evaluation LocationIQ free tier details.

Account Creation

1. Navigate to the LocationIQ signup page.
2. Provide the required information, typically an email address and password.
3. Confirm your email address if prompted, which activates your account.

API Key Retrieval

Once your account is active, your API key will be available in your LocationIQ dashboard:

1. Log in to your LocationIQ account.
2. On the dashboard, locate the section displaying your API key. It is typically a long alphanumeric string.
3. Copy this key. It will be required for every API request you make to LocationIQ services.

It is recommended to store your API key securely and avoid hardcoding it directly into client-side code, especially in production environments. Environmental variables or secure configuration management are preferred methods for handling API keys Google Cloud API key best practices.

Your first request

This section demonstrates how to make a basic geocoding request using your newly acquired API key. Geocoding converts a human-readable address into geographical coordinates (latitude and longitude). We will use the Geocoding API for this example.

API Endpoint and Parameters

The base URL for the Geocoding API is https://us1.locationiq.com/v1/search.php. Key parameters include:

• key: Your LocationIQ API key.
• q: The address or place name you want to geocode.
• format: The desired output format, typically json.

For a complete list of parameters and their descriptions, refer to the LocationIQ Search API documentation.

Example: Geocoding "Eiffel Tower, Paris"

Below are examples of how to make this request using cURL, Python, and JavaScript.

cURL Example

cURL is a command-line tool for making HTTP requests and is useful for quick tests.

curl "https://us1.locationiq.com/v1/search.php?key=YOUR_API_KEY&q=Eiffel%20Tower%2C%20Paris&format=json"

Replace YOUR_API_KEY with your actual API key.

Python Example

Using the requests library in Python:

import requests
import json

api_key = "YOUR_API_KEY"
query = "Eiffel Tower, Paris"
url = f"https://us1.locationiq.com/v1/search.php?key={api_key}&q={query}&format=json"

try:
    response = requests.get(url)
    response.raise_for_status() # Raise an exception for HTTP errors
    data = response.json()
    if data:
        print(json.dumps(data[0], indent=2)) # Print the first result
    else:
        print("No results found.")
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")

Install the requests library if you haven't already: pip install requests.

JavaScript Example (Node.js with node-fetch)

For a Node.js environment, you might use node-fetch (or the built-in fetch in modern Node.js versions).

import fetch from 'node-fetch'; // For Node.js environments without native fetch

const apiKey = "YOUR_API_KEY";
const query = "Eiffel Tower, Paris";
const url = `https://us1.locationiq.com/v1/search.php?key=${apiKey}&q=${query}&format=json`;

async function geocodeAddress() {
  try {
    const response = await fetch(url);
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    const data = await response.json();
    if (data && data.length > 0) {
      console.log(JSON.stringify(data[0], null, 2)); // Print the first result
    } else {
      console.log("No results found.");
    }
  } catch (error) {
    console.error("Error during geocoding request:", error);
  }
}

geocodeAddress();

If using Node.js without native fetch, install node-fetch: npm install node-fetch.

Expected Response

A successful request will return a JSON array of location objects. Each object typically contains details such as lat (latitude), lon (longitude), display_name, and various address components. For example, the first element might look like this (abbreviated):

[
  {
    "place_id": "...",
    "licence": "...",
    "osm_type": "...",
    "osm_id": "...",
    "lat": "48.8582602",
    "lon": "2.2944990",
    "display_name": "Eiffel Tower, Tour Eiffel, 7e Arrondissement, Paris, Île-de-France, 75007, France",
    "address": {
      "building": "Eiffel Tower",
      "road": "Tour Eiffel",
      "city": "Paris",
      "country": "France",
      "postcode": "75007"
    },
    "boundingbox": [
      "48.8579999",
      "48.8585001",
      "2.294",
      "2.295"
    ]
  }
]

Common next steps

After successfully making your first request, you can explore other LocationIQ services and integrate them more deeply into your applications:

• Explore Other APIs: Investigate the Reverse Geocoding API to convert coordinates to addresses, the Routing API for directions, or the Static Maps API to generate map images.
• Implement SDKs: For more complex applications, consider using one of LocationIQ's official SDKs (JavaScript, Python, Ruby, PHP) to streamline API interactions LocationIQ SDK documentation.
• Error Handling: Implement robust error handling in your code to manage API rate limits, invalid requests, and other potential issues.
• Usage Monitoring: Monitor your API usage through the LocationIQ dashboard to stay within your free tier limits or manage your paid plan effectively.
• Advanced Features: Explore advanced parameters for each API, such as language localization, bounding box constraints, or result filtering, to refine your queries LocationIQ API reference guide.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some typical problems and their solutions:

• Invalid API Key:
  • Symptom: HTTP 401 Unauthorized or an error message indicating an invalid key.
  • Solution: Double-check that you have copied your API key correctly from the LocationIQ dashboard. Ensure there are no leading or trailing spaces.
• Missing Parameters:
  • Symptom: HTTP 400 Bad Request or an error message about missing required parameters.
  • Solution: Verify that all mandatory parameters (e.g., q for search, lat and lon for reverse geocoding) are included in your request URL. Consult the LocationIQ specific API reference for required parameters.
• Rate Limit Exceeded:
  • Symptom: HTTP 429 Too Many Requests.
  • Solution: You've exceeded your daily request limit (5,000 for the free tier). Wait until the next day, or consider upgrading your plan LocationIQ pricing plans. For testing, introduce delays between requests.
• Incorrect URL Endpoint:
  • Symptom: HTTP 404 Not Found or a DNS error.
  • Solution: Ensure you are using the correct endpoint for the specific API you are trying to access (e.g., https://us1.locationiq.com/v1/search.php for geocoding).
• Network Issues:
  • Symptom: Connection timeouts or inability to reach the host.
  • Solution: Check your internet connection. If you are behind a firewall or proxy, ensure it allows outgoing connections to us1.locationiq.com.
• Empty Response/No Results:
  • Symptom: The API returns an empty JSON array or a message indicating no results.
  • Solution: The query might be too vague, misspelled, or refer to a location not present in the dataset. Try a more specific or common query.