UtilityActive

Geocoding

Forward geocoding: address string → lat/lon. Reverse geocoding: lat/lon → human-readable address. Powered by OpenStreetMap Nominatim. Returns results array with display_name, lat, lon, type, and structured address object. Provide address (string) for forward, or lat + lon (numbers) for reverse.

Endpointx402 Payment Required

POST

https://agentsvc.io/api/v1/proxy/geocode

Price

$0.002 USDC

Latency P99

~600ms

Provider

agentsvc.io

Input Schema

{
  "type": "object",
  "description": "Provide either 'address' for forward geocoding, or both 'lat' + 'lon' for reverse geocoding.",
  "oneOf": [
    {
      "required": [
        "address"
      ],
      "properties": {
        "address": {
          "type": "string",
          "description": "Address string to geocode (e.g. 'Eiffel Tower, Paris', '1600 Pennsylvania Ave NW, Washington DC', 'Marienplatz 1, Munich')"
        },
        "limit": {
          "type": "integer",
          "default": 1,
          "description": "Max number of results to return (default: 1, max: 5)"
        }
      }
    },
    {
      "required": [
        "lat",
        "lon"
      ],
      "properties": {
        "lat": {
          "type": "number",
          "description": "Latitude for reverse geocoding (e.g. 48.8566)"
        },
        "lon": {
          "type": "number",
          "description": "Longitude for reverse geocoding (e.g. 2.3522)"
        }
      }
    }
  ]
}

Output Schema

{
  "type": "object",
  "required": [
    "mode",
    "results"
  ],
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "forward",
        "reverse"
      ],
      "description": "'forward' if address was geocoded, 'reverse' if coordinates were looked up"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "display_name": {
            "type": "string",
            "description": "Full formatted address string"
          },
          "lat": {
            "type": "number",
            "description": "Latitude"
          },
          "lon": {
            "type": "number",
            "description": "Longitude"
          },
          "type": {
            "type": "string",
            "description": "OSM place type (e.g. 'city', 'house', 'tourism', 'highway')"
          },
          "address": {
            "type": "object",
            "description": "Structured address components",
            "properties": {
              "house_number": {
                "type": "string"
              },
              "road": {
                "type": "string"
              },
              "neighbourhood": {
                "type": "string"
              },
              "suburb": {
                "type": "string"
              },
              "city": {
                "type": "string"
              },
              "state": {
                "type": "string"
              },
              "postcode": {
                "type": "string"
              },
              "country": {
                "type": "string"
              },
              "country_code": {
                "type": "string",
                "description": "ISO 3166-1 alpha-2 (e.g. 'de', 'us', 'fr')"
              }
            }
          },
          "osm_type": {
            "type": "string",
            "description": "OSM element type: 'node', 'way', 'relation'"
          },
          "place_id": {
            "type": "integer",
            "description": "OpenStreetMap place ID"
          }
        }
      }
    },
    "source": {
      "type": "string",
      "description": "Always: 'OpenStreetMap Nominatim'"
    }
  },
  "example": {
    "mode": "forward",
    "results": [
      {
        "display_name": "Eiffel Tower, 5, Avenue Anatole France, Quartier du Gros-Caillou, Paris, Île-de-France, France",
        "lat": 48.8583736,
        "lon": 2.2922926,
        "type": "tourism",
        "address": {
          "road": "Avenue Anatole France",
          "city": "Paris",
          "state": "Île-de-France",
          "postcode": "75007",
          "country": "France",
          "country_code": "fr"
        },
        "osm_type": "way",
        "place_id": 158515771
      }
    ],
    "source": "OpenStreetMap Nominatim"
  }
}

Code Examples

# Step 1: Call without payment → receive 402 with requirements
curl -X POST "https://agentsvc.io/api/v1/proxy/geocode" \
  -H "Content-Type: application/json" \
  -d '{}'

# Step 2: Sign payment using x402 SDK, then retry
curl -X POST "https://agentsvc.io/api/v1/proxy/geocode" \
  -H "Content-Type: application/json" \
  -H "X-Payment: x402 usdc base <your-signed-payment>" \
  -d '{}'

Geocoding

Input Schema

Output Schema

Code Examples

Tags

Service Info