Geocode Structured Address

The geocode_structured_address MCP tool geocodes structured address fields into coordinates and normalized address data.

Use this tool when your application already has separate fields such as street, house number, postcode, city, state, or country. Unlike geocode_address, this tool does not require one combined query string.

Tool name

geocode_structured_address

Request URL

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

Input parameters

Name	Type	Required	Description
`name`	string	No	Place or venue name, for example `Central Station`. Must contain 1 to 1024 characters when provided.
`housenumber`	string	No	House or building number. Use together with `street`. Must contain 1 to 1024 characters when provided.
`street`	string	No	Street name without city, state, or country. Must contain 1 to 1024 characters when provided.
`postcode`	string	No	Postal or ZIP code. Must contain 1 to 1024 characters when provided.
`city`	string	No	City, town, village, or locality. Must contain 1 to 1024 characters when provided.
`state`	string	No	State, region, province, or administrative area. Must contain 1 to 1024 characters when provided.
`country`	string	No	Country name. Must contain 1 to 1024 characters when provided.
`country_codes`	array of strings	No	Optional ISO 3166-1 alpha-2 country code filters. The array can contain up to 10 country codes.
`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`.

The input schema does not require one specific address field, but at least one of name, housenumber, street, postcode, city, state, or country must be present. The schema does not allow additional properties.

Example request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "geocode_structured_address",
    "arguments": {
      "housenumber": "1600",
      "street": "Pennsylvania Ave NW",
      "city": "Washington",
      "state": "DC",
      "country": "United States",
      "country_codes": ["us"],
      "limit": 1,
      "lang": "en"
    }
  }
}

Venue example

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "geocode_structured_address",
    "arguments": {
      "name": "Central Station",
      "city": "Amsterdam",
      "country": "Netherlands",
      "limit": 3
    }
  }
}

Response

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

Example response

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{ ... }"
      }
    ],
    "structuredContent": {
      "address": {
        "housenumber": "1600",
        "street": "Pennsylvania Ave NW",
        "city": "Washington",
        "state": "DC",
        "country": "United States",
        "country_codes": ["us"]
      },
      "count": 1,
      "results": [
        {
          "formatted": "White House, 1600 Pennsylvania Avenue Northwest, Washington, DC 20500, United States of America",
          "address_line1": "White House",
          "address_line2": "1600 Pennsylvania Avenue Northwest, Washington, DC 20500, United States of America",
          "lon": -77.0365528,
          "lat": 38.8976387,
          "result_type": "amenity",
          "country": "United States",
          "country_code": "us"
        }
      ]
    },
    "isError": false
  }
}

Related tools

Geocode Address - use when the address is one free-text query.
Reverse Geocode - use when you have coordinates and need an address.

Related API

For direct HTTP API integration, see Forward Geocoding API.