Location Grounding
x402 protocol service for agents to turn messy location
clues into structured place data
1.0
Location grounding for agents
A paid x402 service that turns messy location clues into structured place data.
Send a landmark, partial name, full address, neighborhood hint, coordinates, nearby reference, venue description, intersection, airport terminal, business name, or ambiguous human phrase.
If the request is location-related, the service returns an x402 payment challenge. After payment, it resolves one location and returns the best available structured fields.
One request resolves one location. Arrays are not accepted at this time.
* * *
2.0
Endpoint
POST /v1/location/resolve
Request body:
{
"locationDetails": "the bean in chicago",
"hints": {
"city": "Chicago",
"countryCode": "US",
"near": "Millennium Park"
}
}
Optional request fields:
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
* * *
3.0
Payment
This is an x402 endpoint.
First request without payment:
POST /v1/location/resolve
The service returns:
402 Payment Required
PAYMENT-REQUIRED: <x402 challenge>
Sign one advertised payment option and retry the same request with:
PAYMENT-SIGNATURE: <signed payment>
A successful paid response includes the location result and a PAYMENT-RESPONSE settlement header.
* * *
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.
* * *
5.0
Example response
{
"resolutionId": "locres_...",
"status": "resolved",
"ambiguityStatus": "single_match",
"confidence": 0.94,
"originalRequest": {
"locationDetails": "the bean in chicago",
"hints": {
"city": "Chicago",
"countryCode": "US"
}
},
"result": {
"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": "Source",
"instructions": "Present these sources immediately after the supported location result.",
"sources": [
{
"title": "Resolved place source",
"uri": "https://...",
"placeId": "..."
}
]
}
}
* * *
6.0
For agents
Use this service when you need to normalize a real-world place from incomplete, informal, or ambiguous location input.
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”
Do not use this service for non-location tasks, batch lookups, routing, emergency response, surveillance, or private/personal location tracking.
* * *
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.
* * *
8.0
Contact
For integration questions, reach us at team@conveen.ai