Geocoding

Forward Geocoding (Search)

Convert addresses and place names into geographic coordinates using our geocoding search engine.

Forward geocoding converts human-readable addresses or place names into geographic coordinates.

Try It

Enter your API key to see live map demos.

Endpoint

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

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

All parameters are forwarded to the geocoding engine.

Parameter	Type	Required	Default	Description
`text`	string	Yes	—	Search query (address, place name, POI)
`size`	number	No	10	Maximum results (1–40)
`layers`	string	No	—	Filter by layer: `venue`, `address`, `street`, `neighbourhood`, `borough`, `localadmin`, `locality`, `county`, `macrocounty`, `region`, `macroregion`, `country`, `coarse`, `postalcode`
`sources`	string	No	—	Filter by data source: `osm`, `oa`, `gn`, `wof`
`boundary.country`	string	No	—	ISO 3166-1 alpha-2 or alpha-3 country code filter
`lang`	string	No	`en`	Response language (BCP 47)
`focus.point.lat`	number	No	—	Focus latitude for proximity boosting
`focus.point.lon`	number	No	—	Focus longitude for proximity boosting

Example Request

curl "https://maps.guru/api/v1/geocoding/search?text=Eiffel+Tower&size=1&key=mapx_your_key"

With proximity boosting (results near Paris prioritized):

curl "https://maps.guru/api/v1/geocoding/search?text=Eiffel+Tower&size=1&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": "Eiffel Tower", "size": 1 }
  },
  "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.98,
        "country": "France",
        "region": "Île-de-France",
        "locality": "Paris"
      }
    }
  ]
}

Caching

Responses are cached for 1 hour at the edge using Cloudflare KV. The X-Cache response header indicates cache status:

X-Cache: HIT — served from cache
X-Cache: MISS — fetched from the geocoding engine and cached

Layers Reference

Use the layers parameter to restrict results to specific place types:

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

Data Sources

Use the sources parameter to restrict results to specific datasets:

Source	Description
`osm`	OpenStreetMap
`oa`	OpenAddresses
`gn`	GeoNames
`wof`	Who's on First

Static Maps

Generate static map images for emails, reports, and social sharing.

Reverse Geocoding

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