Geocoding

Autocomplete

Get real-time type-ahead suggestions as users type.

Autocomplete returns place suggestions as a user types, making it ideal for search boxes and address inputs. Results are optimized for partial text and update with each keystroke.

Try It

Enter your API key to see live map demos.

Don't have one? Get your free API key

Endpoint

GET https://maps.guru/api/v1/geocoding/autocomplete?text={partial}&key={api_key}

Autocomplete responses are not cached — this endpoint is designed for real-time type-ahead where each request reflects the latest partial input.

Authentication

API key required via one of:

Query parameter: ?key=mapx_your_key
Header: Authorization: Bearer mapx_your_key
Header: X-API-Key: mapx_your_key

Parameters

Parameter	Type	Required	Default	Description
`text`	string	Yes	—	Partial search text (minimum 2 characters recommended)
`focus.point.lat`	number	No	—	Focus latitude — results near this point are ranked higher
`focus.point.lon`	number	No	—	Focus longitude — results near this point are ranked higher
`size`	number	No	10	Maximum results (1–40)
`layers`	string	No	—	Filter by layer: `venue`, `address`, `street`, `neighbourhood`, `locality`, `county`, `region`, `country`, `coarse`, `postalcode`
`sources`	string	No	—	Filter by data source: `osm`, `oa`, `gn`, `wof`
`lang`	string	No	`en`	Response language (BCP 47)

Example Request

Autocomplete for the partial text "eiff":

curl "https://maps.guru/api/v1/geocoding/autocomplete?text=eiff&key=mapx_your_key"

With a focus point to prioritize results near Paris:

curl "https://maps.guru/api/v1/geocoding/autocomplete?text=eiff&focus.point.lat=48.8566&focus.point.lon=2.3522&key=mapx_your_key"

Example Response

Responses are GeoJSON FeatureCollection format:

{
  "geocoding": {
    "version": "0.2",
    "query": { "text": "eiff", "size": 10 }
  },
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [2.2945, 48.8584]
      },
      "properties": {
        "id": "way:5013364",
        "gid": "openstreetmap:venue:way/5013364",
        "layer": "venue",
        "source": "openstreetmap",
        "name": "Tour Eiffel",
        "label": "Tour Eiffel, Paris, Île-de-France, France",
        "confidence": 0.95,
        "country": "France",
        "region": "Île-de-France",
        "locality": "Paris"
      }
    }
  ]
}

Usage Tips

Debounce requests — fire autocomplete requests after a short delay (150–300ms) rather than on every keystroke to avoid unnecessary API calls.

Use focus.point — if you know the user's approximate location, pass it as focus.point.lat/focus.point.lon to surface nearby results first.

Use gid for follow-up lookups — once a user selects a suggestion, use the gid from the result with the Place Lookup endpoint to fetch full details.

Layers Reference

Layer	Description
`venue`	Points of interest, businesses, landmarks
`address`	Street-level addresses
`street`	Street names
`neighbourhood`	Neighbourhoods and districts
`locality`	Cities and towns
`county`	Counties
`region`	States and provinces
`country`	Countries
`postalcode`	Postal codes
`coarse`	All administrative layers combined

Reverse Geocoding

Convert geographic coordinates into human-readable addresses using our geocoding engine.

Place Lookup

Fetch full details for one or more places by their GID (global identifier), including building footprints when available.