Geocoding

Place Lookup

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

Place Lookup retrieves full details for one or more places using their GID (global identifier). Use this after an autocomplete or search to fetch complete information about a selected place — including building footprints, contact details, and rich category metadata when available.

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/place?ids={gid1,gid2}&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

Parameter	Type	Required	Description
`ids`	string	Yes	Comma-separated list of GIDs (e.g., `overture:venue:06921e33-6839-4f34-a932-711eebfe6c6e`)

What is a GID?

A GID (global identifier) uniquely identifies a place across all data sources. GIDs follow the format:

{source}:{layer}:{id}

For example:

overture:venue:06921e33-6839-4f34-a932-711eebfe6c6e — an Overture venue (with optional building footprint)
openstreetmap:venue:way/5013364 — an OSM way
openstreetmap:address:node/123456789 — an OSM address node
whosonfirst:locality:101748417 — a Who's on First locality
geonames:locality:2988507 — a GeoNames locality

GIDs are returned in the gid property of every search, reverse geocoding, and autocomplete result.

Example Request

Look up an Overture venue by its GID:

curl "https://maps.guru/api/v1/geocoding/place?ids=overture:venue:06921e33-6839-4f34-a932-711eebfe6c6e&key=mapx_your_key"

Look up multiple places at once:

curl "https://maps.guru/api/v1/geocoding/place?ids=overture:venue:06921e33-6839-4f34-a932-711eebfe6c6e,whosonfirst:locality:101748417&key=mapx_your_key"

Example Response

Responses are GeoJSON FeatureCollection format. When a place has a known building footprint, it's included as properties.building.geometry:

{
  "geocoding": {
    "version": "0.2",
    "attribution": "https://maps.guru/attribution",
    "query": {
      "ids": [
        {
          "source": "overture",
          "layer": "venue",
          "id": "06921e33-6839-4f34-a932-711eebfe6c6e"
        }
      ],
      "private": false,
      "lang": {
        "name": "French",
        "iso6391": "fr",
        "iso6393": "fra",
        "via": "header",
        "defaulted": false
      }
    },
    "engine": {
      "name": "Pelias",
      "author": "Mapzen",
      "version": "1.0"
    },
    "timestamp": 1777134689110
  },
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [73.806659, 15.458366]
      },
      "properties": {
        "id": "06921e33-6839-4f34-a932-711eebfe6c6e",
        "gid": "overture:venue:06921e33-6839-4f34-a932-711eebfe6c6e",
        "layer": "venue",
        "source": "overture",
        "source_id": "06921e33-6839-4f34-a932-711eebfe6c6e",
        "country_code": "IN",
        "name": "Tanuja Stores",
        "accuracy": "point",
        "country": "India",
        "country_gid": "whosonfirst:country:85632469",
        "country_a": "IND",
        "region": "Goa",
        "region_gid": "whosonfirst:region:85672255",
        "region_a": "GA",
        "county": "North Goa",
        "county_gid": "whosonfirst:county:890508373",
        "county_a": "NG",
        "building": {
          "id": "1b37cd3d-a4d6-493c-b7af-33834a01d036",
          "geometry": {
            "type": "Polygon",
            "coordinates": [
              [
                [73.8065964, 15.4581099],
                [73.8067326, 15.4581264],
                [73.806704, 15.4583484],
                [73.8066619, 15.4583433],
                [73.806659, 15.4583658],
                [73.8065852, 15.4583569],
                [73.8066128, 15.4581424],
                [73.8065925, 15.45814],
                [73.8065964, 15.4581099]
              ]
            ]
          }
        },
        "label": "Tanuja Stores, GA, India",
        "addendum": {
          "overture": {
            "building_id": "1b37cd3d-a4d6-493c-b7af-33834a01d036",
            "has_building_footprint": true,
            "operating_status": "open",
            "phones": ["+919860604216"],
            "emails": ["tanujastores@yahoo.com"],
            "socials": ["https://www.facebook.com/289113547966562"],
            "confidence": 0.7237939238548279,
            "basic_category": "personal_care_and_beauty_store",
            "taxonomy": {
              "primary": "beauty_supply_store",
              "hierarchy": [
                "shopping",
                "specialty_store",
                "personal_care_and_beauty_store",
                "beauty_supply_store"
              ]
            },
            "categories": {
              "primary": "cosmetic_and_beauty_supplies",
              "alternate": ["shopping", "beauty_and_spa"]
            }
          }
        }
      }
    }
  ],
  "bbox": [73.806659, 15.458366, 73.806659, 15.458366]
}

Response Fields

Top-Level

Field	Type	Description
`type`	string	Always `"FeatureCollection"`
`geocoding`	object	Engine metadata (version, query echo, language, timestamp)
`features`	array	Array of GeoJSON `Feature` objects (one per resolved GID)
`bbox`	array	`[minLon, minLat, maxLon, maxLat]` covering all features

Feature Properties

Field	Type	Description
`id`	string	Source-specific ID (e.g., the Overture UUID)
`gid`	string	Global identifier (`{source}:{layer}:{id}`)
`layer`	string	Layer type (`venue`, `address`, `locality`, etc.)
`source`	string	Data source (`overture`, `openstreetmap`, `whosonfirst`, `geonames`)
`name`	string	Place name (`"Tanuja Stores"`)
`label`	string	Full display label (`"Tanuja Stores, GA, India"`)
`accuracy`	string	`"point"` (exact) or `"centroid"` (approximated)
`country`, `region`, `county`, `locality`	string	Administrative hierarchy
`country_code`, `region_a`, `country_a`	string	ISO codes
`building`	object	Optional. Building footprint, when available — see below
`addendum`	object	Source-specific extras (categories, contact info, taxonomy)

Building Footprint

When a venue has a known building footprint, it's returned in properties.building:

"building": {
  "id": "1b37cd3d-a4d6-493c-b7af-33834a01d036",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[lon, lat], [lon, lat], ...]]
  }
}

Field	Type	Description
`building.id`	string	Building identifier (Overture building UUID)
`building.geometry`	GeoJSON Polygon	Building outline as a GeoJSON Polygon

The addendum.overture.has_building_footprint boolean also flags this. Not all venues have footprints — check before rendering.

Rendering Place + Building on MapLibre

When a feature has building.geometry, render it as a fill layer with 0.5 opacity alongside the point marker:

const feature = response.features[0];
const coords = feature.geometry.coordinates;     // [lon, lat]
const building = feature.properties.building;     // optional

// --- 1. Add center marker ---
new maplibregl.Marker({ color: '#f59e0b' })
  .setLngLat(coords)
  .setPopup(new maplibregl.Popup().setText(feature.properties.label))
  .addTo(map);

// --- 2. Render building polygon when available ---
if (building?.geometry) {
  map.addSource('building', {
    type: 'geojson',
    data: {
      type: 'Feature',
      geometry: building.geometry,
      properties: { id: building.id }
    }
  });

  // Fill layer at 0.5 opacity
  map.addLayer({
    id: 'building-fill',
    type: 'fill',
    source: 'building',
    paint: {
      'fill-color': '#f59e0b',
      'fill-opacity': 0.5
    }
  });

  // Optional: outline for visual definition
  map.addLayer({
    id: 'building-outline',
    type: 'line',
    source: 'building',
    paint: {
      'line-color': '#d97706',
      'line-width': 2
    }
  });
}

// --- 3. Zoom to the place ---
map.flyTo({ center: coords, zoom: 18 });

This shows an amber marker at the place's anchor point, with the building footprint rendered beneath as a semi-transparent polygon — making it easy to see both the precise location and the building's actual shape.

Building footprints are most useful at zoom 16+. The Try It demo above flies to zoom 18 to make the polygon visible.

Bounding Box (bbox)

Place Lookup also returns a top-level bbox covering all features in the response:

"bbox": [73.806659, 15.458366, 73.806659, 15.458366]
//        West       South      East       North

The bbox format is [minLon, minLat, maxLon, maxLat] (GeoJSON convention). For a single point lookup, all four values match the feature's coordinates.

You can use map.fitBounds(bbox, { padding: 50, maxZoom: 18 }) to frame the entire result set.

Caching

Responses are cached for 24 hours 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

Common Workflow

Place Lookup is typically used as the second step after autocomplete:

User types in a search box → call Autocomplete with partial text
User selects a suggestion from the dropdown
Use the gid from the selected result → call Place Lookup for full details
Render the building footprint (if returned), or fall back to the point marker

Autocomplete

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

Nearby Search

Find places, venues, and points of interest near a geographic coordinate using our Pelias-powered geocoding engine.