Location grounding for agents

2.0

Endpoint

POST /v1/location/resolve

Request body:

agentCustomerId clientRequestId hints.city hints.region hints.countryCode hints.near hints.languageCode hints.timezone hints.coordinates

If the request is not location-related, the service returns:

422 cannot_service

{
  "locationDetails": "the bean in chicago",
  "hints": {
    "city": "Chicago",
    "countryCode": "US",
    "near": "Millennium Park"
  }
}

3.0

Payment

This is an x402 endpoint. The challenge advertises the current payment options and amount.

First request without payment

POST /v1/location/resolve

Challenge returned

402 Payment Required
PAYMENT-REQUIRED: <x402 challenge>

Signed retry

PAYMENT-SIGNATURE: <signed payment>

Settlement response

PAYMENT-RESPONSE: <settlement>

POST /v1/location/resolve

402 Payment Required
PAYMENT-REQUIRED: <x402 challenge>

PAYMENT-SIGNATURE: <signed payment>
PAYMENT-RESPONSE: <settlement>

4.0

Response

The response includes the original request, a resolution ID, match status, confidence, and any location fields the service can support.

Possible result fields:

exactName formattedAddress city stateOrProvince postalCode countryCode latitude longitude categories traits summary operatingStatus openingHours phone website rating ratingCount priceTier accessibility amenities

All location fields are optional. If a field cannot be found with confidence, it is omitted.

If source attribution is returned, present the provided source title and link immediately after the supported result.

Live explanation

Messy clue to structured place

This visual demo is local only. It shows the shape of a successful resolution without calling the paid endpoint or creating an x402 charge.

locationDetails the bean in chicago

structured result

5.0

Example response

{
  "schemaVersion": "2026-08-05",
  "resolutionId": "locres_...",
  "status": "resolved",
  "ambiguityStatus": "single_match",
  "confidence": 0.94,
  "originalRequest": {
    "locationDetails": "the bean in chicago",
    "hints": {
      "city": "Chicago",
      "countryCode": "US"
    }
  },
  "result": {
    "locationId": "loc_cloud_gate",
    "exactName": "Cloud Gate",
    "formattedAddress": "201 E Randolph St, Chicago, IL 60602, US",
    "city": "Chicago",
    "stateOrProvince": "Illinois",
    "postalCode": "60602",
    "countryCode": "US",
    "latitude": 41.8826,
    "longitude": -87.6226,
    "categories": ["landmark", "public_art"],
    "traits": ["landmark", "public art"]
  },
  "attribution": {
    "required": true,
    "displayName": "Google Maps",
    "instructions": "Present these sources immediately after the supported location result.",
    "sources": [
      {
        "title": "Cloud Gate",
        "uri": "https://maps.google.com/?cid=...",
        "placeId": "places/..."
      }
    ]
  }
}

6.0

For agents

Use this service when you need to normalize a real-world place from incomplete, informal, or ambiguous location input.

Do not use this service for non-location tasks, batch lookups, routing, emergency response, surveillance, or private/personal location tracking.

Good inputs

"the bean in chicago"
"coffee near the north entrance of Golden Gate Park"
"1600 Amphitheatre Parkway"
"JFK Terminal 4"
"intersection of 1st and Pike Seattle"
"restaurant beside the old train station in Denver"
"40.7484, -73.9857"
"the pharmacy across from the convention center"
"the old post office building in DC"

7.0

Contract

One request in. One x402 payment. One resolved location out.

If the location cannot be resolved confidently, the service returns an unresolved or ambiguous response with the fields it can support.

No accounts are required. The payment is the authorization.

llms.txt openapi.json sitemap.xml robots.txt