Geocode Address

The geocode_address MCP tool converts a street address or free-text location query into coordinates and structured address data.

Use this tool when the user provides an address as one text string, for example a full street address, venue query, postcode, or city name.

Tool name

geocode_address

Request URL

https://api.geoapify.com/v1/mcp?apiKey=YOUR_API_KEY

Input parameters

Name	Type	Required	Description
`query`	string	Yes	Street address or free-text location query to geocode. Must contain 1 to 1024 characters.
`limit`	integer	No	Maximum number of results to return. Supported range: `1` to `10`. Default: `5`.
`lang`	string	No	Result language as a supported two-letter language code. Default: `en`.
`country_codes`	array of strings	No	Optional ISO 3166-1 alpha-2 country code filters. The array can contain up to 10 country codes.

The input schema does not allow additional properties.

Example request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "geocode_address",
    "arguments": {
      "query": "1600 Pennsylvania Ave NW, Washington, DC",
      "limit": 1,
      "lang": "en",
      "country_codes": ["us"]
    }
  }
}

Minimal request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "geocode_address",
    "arguments": {
      "query": "Paris, France"
    }
  }
}

Response

The tool returns matching locations with coordinates and structured address properties. Set limit to control how many candidates the response can include.

Example response

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{ ... }"
      }
    ],
    "structuredContent": {
      "query": "Berlin",
      "count": 1,
      "results": [
        {
          "formatted": "Berlin, Germany",
          "address_line1": "Berlin",
          "address_line2": "Germany",
          "lon": 13.3951309,
          "lat": 52.5173885,
          "result_type": "city",
          "country": "Germany",
          "country_code": "de"
        }
      ]
    },
    "isError": false
  }
}

Related tools

Geocode Structured Address - use when address parts are already separated.
Reverse Geocode - use when you have coordinates and need an address.

Related API

For direct HTTP API integration, see Forward Geocoding API.