canonical: https://jentic.com/apis/locationiq.com/locationiq-api

# LocationIQ API

LocationIQ provides global geocoding, reverse geocoding, routing, and place-search services backed by OpenStreetMap data and a worldwide datacentre footprint. The API supports forward, structured, and postal-code geocoding, autocomplete suggestions, nearby place search, time-zone lookups, and turn-by-turn directions across driving, cycling, and walking profiles. Account balance can be queried to track API usage against quota.

## For AI agents

Geocode addresses, reverse-geocode coordinates, find nearby places, and calculate driving directions worldwide using OpenStreetMap data.

## Scope

Does not handle map tile rendering, vector tile hosting, or commercial truck-specific routing - use for geocoding, reverse geocoding, autocomplete, and basic routing only.

## Capabilities

- Convert free-form or structured addresses into latitude and longitude with the /search endpoint
- Reverse-geocode coordinate pairs into formatted addresses via /reverse
- Suggest matching addresses while users type using /autocomplete
- Find points of interest within a radius of a coordinate through /nearby
- Calculate driving, cycling, or walking routes with /directions/{profile}/{coordinates}
- Resolve a coordinate to its IANA time zone using /timezone
- Track remaining daily quota by querying /balance

## Use cases

### Address Autocomplete in Checkout

Reduce cart abandonment by suggesting validated addresses as shoppers type. The /autocomplete endpoint returns ranked address candidates that resolve to canonical coordinates, so downstream shipping and tax calculations use clean data. Integration is straightforward because results follow the standard Nominatim format.

Example prompt: Call /autocomplete with q='221b baker' and limit=5 to return the top five matching addresses worldwide.

### Delivery Route Planning

Calculate driving directions between a depot and a delivery stop with the /directions/{profile}/{coordinates} endpoint. The response includes distance, duration, and turn-by-turn steps usable in dispatcher dashboards. Profiles cover driving, cycling, and walking so the same API powers both fleet and last-mile workflows.

Example prompt: Request /directions/driving/-73.989,40.733;-73.968,40.785 to get the driving route distance and duration in JSON.

### Reverse Geocoding for Mobile Check-ins

Translate a phone's GPS reading into a human-readable address with /reverse. This powers check-in features, ride pickup confirmations, and field-service apps where the user does not type an address. Responses include house number, road, suburb, city, postcode, and country.

Example prompt: Send GET /reverse?lat=37.7749&lon=-122.4194&format=json and parse the display_name field.

### AI Agent Location Lookup via Jentic

Agents that answer location questions can call LocationIQ through Jentic without managing API keys directly. Jentic exposes the geocoding, reverse-geocoding, and directions operations as MCP tools, so the agent picks the right one by intent rather than reading docs. The API key stays in your Jentic One instance.

Example prompt: Through Jentic, search 'geocode an address', load the LocationIQ /search schema, and execute it with the user's input string.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /search | Forward geocoding from a free-form query |
| GET | /reverse | Reverse geocode coordinates to an address |
| GET | /autocomplete | Address autocomplete suggestions |
| GET | /nearby | Find places within a radius of a coordinate |
| GET | /directions/{profile}/{coordinates} | Get a route for a transport profile |
| GET | /timezone | Look up the time zone for a coordinate |
| GET | /balance | Check remaining account quota |

## Key resources

- **Search** — Forward, structured, and postal-code geocoding endpoints that convert addresses to coordinates
- **Reverse** — Convert latitude/longitude pairs back into formatted addresses
- **Autocomplete** — Return ranked address suggestions for partial query strings
- **Nearby** — List points of interest near a given coordinate (BETA)
- **Directions** — Calculate routes between coordinates for driving, cycling, or walking profiles
- **Timezone** — Look up the IANA time zone for any coordinate
- **Balance** — Query remaining daily request quota on the account

## Why Jentic

- **Setup:** Wiring LocationIQ by hand means passing your access token as a query parameter on every request, picking the right US or EU endpoint host, and encoding geocoding and routing parameters yourself. Through Jentic you install once, import LocationIQ from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** LocationIQ is a stateless geocoding service with no per-account resources in the URL path, so scoping is by operation: limit the agent to the operations it needs, such as forward geocoding and reverse geocoding, and leave out directions or nearby search if the agent does not need them.
- **Credential handling:** Your LocationIQ API key is stored once, encrypted, by your own Jentic One instance and appended to the request at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'geocode an address' or 'reverse geocode coordinates', and Jentic returns the matching LocationIQ operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **OpenCage Geocoding API** — Another OpenStreetMap-backed geocoding API with a single global endpoint
- **HERE Maps API** — Enterprise-grade geocoding, routing, and traffic data from a commercial provider
- **GraphHopper Directions API** — Specialised routing engine often paired with a separate geocoder
- **Positionstack API** — Forward and reverse geocoding API with global coverage

## FAQ

### What authentication does the LocationIQ API use?

LocationIQ uses an API key passed as the `key` query parameter on every request. Through Jentic the key is stored in the encrypted vault and injected at execution time, so the key never appears in the agent's context.

### Can I get turn-by-turn driving directions with the LocationIQ API?

Yes. Call GET /directions/{profile}/{coordinates} with profile set to driving, cycling, or walking and a semicolon-separated coordinate list. The response returns distance in metres, duration in seconds, and step-by-step instructions.

### What are the rate limits for the LocationIQ API?

Rate limits depend on your plan tier. The free tier allows 5,000 requests per day at 2 requests per second. Use GET /balance to read your remaining quota at any time.

### How do I geocode an address with LocationIQ through Jentic?

Run `pip install jentic`, then search Jentic for 'geocode an address', load the LocationIQ /search operation, and execute it with the address string. Jentic returns the JSON response with lat, lon, and the parsed address components.

### Does LocationIQ support reverse geocoding for mobile coordinates?

Yes. Send GET /reverse with lat and lon parameters and the API returns a structured address including house number, road, city, postcode, and country, suitable for mobile check-in or ride-hailing apps.

### Is the LocationIQ API free?

LocationIQ offers a free tier with 5,000 daily requests and paid tiers with higher quotas, commercial use rights, and SLA guarantees. Pricing is published at locationiq.com/pricing.

### Can I limit what my agent is allowed to do with the LocationIQ API?

Yes. LocationIQ is a stateless geocoding service with no per-account resources in the URL path, so you scope access by operation in your own self-hosted Jentic One instance, where your rules decide which operations and credentials the agent may use. For example, you can allow the agent to call forward geocoding on /search and reverse geocoding on /reverse while leaving out /directions/{profile}/{coordinates} and /nearby if it does not need routing or place search. The stored API key is injected only for the operations you permit, so the agent can never reach an endpoint you have not enabled.