API Documentation - LatLng Geocoding, Places & Map Tiles API

🔑 Authentication

All API requests require an API key. There are two types of keys:

Key Type	Prefix	Use Case
Server Key	`latlng_`	All APIs — geocoding, reverse, places, tiles. Keep secret in backend code.
Maps Key	`pk_latlng_`	Map tiles only. Safe to embed in client-side code. Can be domain-restricted.

Header Authentication (Server Key)

X-Api-Key: latlng_your_key_here

Query Parameter (Maps Key)

https://tiles.latlng.work/v1/metadata?key=pk_latlng_your_key

Get your API keys from the dashboard.

🌍 Forward Geocoding

Convert an address or place name into geographic coordinates.

GET https://api.latlng.work/api

Parameters

Parameter	Type	Description
`q` required	string	The address or place name to geocode
`limit`	integer	Maximum number of results (default: 10)
`lang`	string	Language for results (e.g., "en", "de", "fr")

Example Request

curl "https://api.latlng.work/api?q=Seattle,WA" \
  -H "X-Api-Key: your_api_key"

Example Response

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [-122.3321, 47.6062]
      },
      "properties": {
        "name": "Seattle",
        "state": "Washington",
        "country": "United States",
        "type": "city"
      }
    }
  ]
}

📍 Reverse Geocoding

Convert geographic coordinates into a human-readable address.

GET https://api.latlng.work/reverse

Parameters

Parameter	Type	Description
`lat` required	number	Latitude coordinate
`lon` required	number	Longitude coordinate

Example Request

curl "https://api.latlng.work/reverse?lat=47.6062&lon=-122.3321" \
  -H "X-Api-Key: your_api_key"

📌 Places Nearby

Find points of interest near a location using pre-built geo-tiles. Places data is powered by the Overture Maps Foundation.

GET https://api.latlng.work/places/nearby

Parameters

Parameter	Type	Description
`lat` required	number	Latitude of the center point
`lon` required	number	Longitude of the center point
`radius`	integer	Search radius in meters (default: 1000, max: 5000)
`category`	string	Filter by category (e.g., "hotel", "restaurant")
`limit`	integer	Maximum results to return (default: 20)

Example Request

curl "https://api.latlng.work/places/nearby?lat=47.6062&lon=-122.3321&radius=1000&limit=5" \
  -H "X-Api-Key: your_api_key"

Example Response

{
  "type": "nearby",
  "center": { "lat": 47.6062, "lon": -122.3321 },
  "radius": 1000,
  "count": 2,
  "places": [
    {
      "name": "Pike Place Market",
      "lat": 47.6097,
      "lon": -122.3425,
      "category": "marketplace",
      "distance_m": 328
    },
    {
      "name": "Starbucks Reserve Roastery",
      "lat": 47.6140,
      "lon": -122.3281,
      "category": "cafe",
      "distance_m": 912
    }
  ]
}

🔍 Places Search

Search for places by name with optional location bias and category filtering.

GET https://api.latlng.work/places/search

Parameters

Parameter	Type	Description
`q` required	string	Search query (e.g., "Starbucks")
`lat`	number	Latitude for location bias
`lon`	number	Longitude for location bias
`category`	string	Filter by category
`country`	string	Filter by country code (e.g., "US")
`limit`	integer	Maximum results (default: 10)

Example Request

curl "https://api.latlng.work/places/search?q=Starbucks&lat=47.60&lon=-122.33&limit=5" \
  -H "X-Api-Key: your_api_key"

Example Response

{
  "type": "search",
  "query": "Starbucks",
  "count": 2,
  "places": [
    {
      "name": "Starbucks",
      "lat": 47.6101,
      "lon": -122.3420,
      "category": "cafe",
      "distance_m": 845,
      "match_score": 1.0
    }
  ]
}

💡 Places Autosuggest

Get place name suggestions as the user types. Ideal for search-as-you-type UIs.

GET https://api.latlng.work/places/autosuggest

Parameters

Parameter	Type	Description
`q` required	string	Partial query (min 2 characters)
`lat`	number	Latitude for location bias
`lon`	number	Longitude for location bias
`limit`	integer	Maximum suggestions (default: 5)

Example Request

curl "https://api.latlng.work/places/autosuggest?q=star&lat=47.60&lon=-122.33" \
  -H "X-Api-Key: your_api_key"

Example Response

{
  "type": "autosuggest",
  "query": "star",
  "suggestions": [
    { "name": "Starbucks", "category": "cafe", "similarity": 0.85 },
    { "name": "Star Nails", "category": "beauty_salon", "similarity": 0.72 }
  ]
}

📂 Places Categories

List all available place categories you can use to filter results. Categories follow the Overture Maps taxonomy. View full categories list →

GET https://api.latlng.work/places/categories

Example Request

curl "https://api.latlng.work/places/categories" \
  -H "X-Api-Key: your_api_key"

Example Response

{
  "categories": [
    { "name": "restaurant", "count": 584210 },
    { "name": "cafe", "count": 312045 },
    { "name": "hotel", "count": 198432 }
  ]
}

🗺️ Map Tiles API

Serve OpenStreetMap-based vector tiles for MapLibre GL JS. Uses a Maps Key (pk_latlng_) passed as a query parameter.

TileJSON Metadata

GET https://tiles.latlng.work/v1/metadata?key=pk_latlng_...

Returns a TileJSON spec describing tile sources, bounds, and attribution. This is the URL you pass to MapLibre's source.url.

Vector Tiles

GET https://tiles.latlng.work/v1/tiles/{z}/{x}/{y}.pbf?key=pk_latlng_...

Returns Protobuf-encoded vector tiles. Normally accessed by MapLibre automatically — you don't call this directly.

MapLibre GL JS Integration

<link rel="stylesheet" href="https://unpkg.com/maplibre-gl/dist/maplibre-gl.css">
<script src="https://unpkg.com/maplibre-gl/dist/maplibre-gl.js"></script>
<script src="https://unpkg.com/protomaps-themes-base"></script>

<div id="map" style="width:100%; height:400px;"></div>

<script>
const map = new maplibregl.Map({
  container: 'map',
  style: {
    version: 8,
    glyphs: 'https://protomaps.github.io/basemaps-assets/fonts/{fontstack}/{range}.pbf',
    sprite: 'https://protomaps.github.io/basemaps-assets/sprites/v4/light',
    sources: {
      protomaps: {
        type: 'vector',
        url: 'https://tiles.latlng.work/v1/metadata?key=pk_latlng_YOUR_KEY'
      }
    },
    layers: protomapsL.layers('protomaps', protomapsL.namedFlavor('light'), { lang: 'en' })
  },
  center: [-122.33, 47.61],
  zoom: 13
});
</script>

⚠️ Rate Limits

Usage is tracked per-user across all API keys with a unified quota — all API calls (geocoding, reverse, places, tiles) count toward one shared pool.

Plan	Quota	Period
Free	3,000 total API calls	Per day
Pro	1,000,000 total API calls	Per month
Enterprise	Custom	Custom

Every geocode, reverse geocode, places search, and tile request counts equally toward your quota.

Rate limit headers are included in every response:

Header	Description
`X-RateLimit-Limit`	Your plan's total request limit for the current period
`X-RateLimit-Remaining`	Requests remaining in current period (across all API types)

❌ Error Codes

Code	Description
`400`	Bad Request — Missing or invalid parameters
`401`	Unauthorized — Invalid or missing API key
`403`	Forbidden — Public key used on server-only endpoint, or domain not allowed
`429`	Too Many Requests — Rate limit exceeded
`500`	Internal Server Error