Documentation

GeoResolver provides a REST API for spatial intelligence — geocoding, proximity search, land use classification, building footprints, elevation data, and batch processing. All responses are returned as JSON.

Base URL

https://api.georesolver.com/v1

Authentication

All API requests require an API key. Include it in the X-API-Key header:

Header

X-API-Key: gr_live_your_api_key

You can also pass the key as a query parameter for quick testing:

Query parameter (testing only)

GET /v1/geocode?address=...&api_key=gr_live_your_api_key

Create your API key from the Dashboard. Keys are shown once at creation — copy and store them securely.

Endpoints

GET/v1/geocode

Forward geocoding. Convert a street address into geographic coordinates.

Parameters

Name	Type	Required	Description
address	string	Required	Street address to geocode

Example Response

200 OK

{
  "lat": 38.8977,
  "lng": -77.0365,
  "confidence": 0.98,
  "formatted_address": "1600 Pennsylvania Avenue NW, Washington, DC 20500",
  "source": "openstreetmap",
  "components": {
    "house_number": "1600",
    "road": "Pennsylvania Avenue NW",
    "city": "Washington",
    "state": "District of Columbia",
    "postcode": "20500",
    "country": "United States"
  }
}

Try in Playground →

GET/v1/reverse

Reverse geocoding. Convert geographic coordinates into a human-readable address.

Parameters

Name	Type	Required	Description
lat	number	Required	Latitude of the point
lon	number	Required	Longitude of the point

Example Response

200 OK

{
  "lat": 38.8977,
  "lng": -77.0365,
  "confidence": 0.95,
  "formatted_address": "1600 Pennsylvania Avenue NW, Washington, DC 20500",
  "source": "openstreetmap",
  "components": {
    "house_number": "1600",
    "road": "Pennsylvania Avenue NW",
    "city": "Washington",
    "state": "District of Columbia",
    "postcode": "20500",
    "country": "United States"
  }
}

Try in Playground →

GET/v1/proximity

Find nearby points of interest within a radius. Supports categories like schools, hospitals, parks, restaurants, and more.

Parameters

Name	Type	Required	Description
lat	number	Required	Latitude of the center point
lon	number	Required	Longitude of the center point
category	string	Required	POI category: schools, hospitals, parks, transit, restaurants, banks, pharmacies, supermarkets, fuel, parking
radius	integer	Optional	Search radius in meters

Example Response

200 OK

{
  "results": [
    {
      "name": "Central Park",
      "category": "parks",
      "distance_m": 245.3,
      "lat": 40.7829,
      "lon": -73.9654,
      "tags": {
        "leisure": "park"
      }
    }
  ],
  "count": 1,
  "radius": 1000,
  "category": "parks"
}

Try in Playground →

GET/v1/land-use

Get land use classification for a location. Returns the primary type and area breakdown within the given radius.

Parameters

Name	Type	Required	Description
lat	number	Required	Latitude of the point
lon	number	Required	Longitude of the point
radius	integer	Optional	Analysis radius in meters

Example Response

200 OK

{
  "primary_type": "residential",
  "source": "openstreetmap",
  "areas": [
    {
      "type": "residential",
      "area_pct": 65.2
    },
    {
      "type": "commercial",
      "area_pct": 20.1
    },
    {
      "type": "green",
      "area_pct": 14.7
    }
  ]
}

Try in Playground →

GET/v1/buildings

Find buildings around a location. Returns building type, approximate area, levels, and address when available.

Parameters

Name	Type	Required	Description
lat	number	Required	Latitude of the center point
lon	number	Required	Longitude of the center point
radius	integer	Optional	Search radius in meters

Example Response

200 OK

{
  "results": [
    {
      "building_type": "commercial",
      "area_sqm": 1250.4,
      "levels": 3,
      "address": "Main St 42, Springfield",
      "lat": 40.7128,
      "lon": -74.006,
      "tags": {
        "building": "commercial"
      }
    }
  ],
  "count": 1,
  "radius": 500
}

Try in Playground →

GET/v1/elevation

Get elevation, slope, and aspect for any location. Uses high-resolution global terrain data.

Parameters

Name	Type	Required	Description
lat	number	Required	Latitude of the point
lon	number	Required	Longitude of the point

Example Response

200 OK

{
  "elevation_m": 125,
  "slope_pct": 8.3,
  "aspect_deg": 225,
  "source": "copernicus_dem"
}

Try in Playground →

GET/v1/parcels

Get cadastral parcel data for a location. Currently available for Poland only. Returns parcel ID, commune, county, voivodeship, and WKT geometry.

Parameters

Name	Type	Required	Description
lat	number	Required	Latitude of the point
lon	number	Required	Longitude of the point

Example Response

200 OK

{
  "parcel_id": "141201_1.0001.6509/2",
  "commune": "Warszawa",
  "county": "Warszawa",
  "voivodeship": "mazowieckie",
  "geometry_wkt": "POLYGON((...)) ",
  "source": "uldk",
  "country": "PL"
}

Try in Playground →

GET/v1/boundaries

Get administrative boundaries for a location. Returns admin levels (country, region, county, municipality) with names and official codes.

Parameters

Name	Type	Required	Description
lat	number	Required	Latitude of the point
lon	number	Required	Longitude of the point

Example Response

200 OK

{
  "admin_levels": [
    {
      "name": "Polska",
      "level": 2,
      "code": "PL",
      "name_local": "Poland"
    },
    {
      "name": "mazowieckie",
      "level": 4,
      "code": "14"
    },
    {
      "name": "Warszawa",
      "level": 6,
      "code": "1465"
    }
  ],
  "country": "Polska",
  "country_code": "PL",
  "source": "openstreetmap"
}

Try in Playground →

GET/v1/demographics

Get demographic data for a location. In Poland, returns official GUS statistics (population, density, area). Globally, returns OSM population data.

Parameters

Name	Type	Required	Description
lat	number	Required	Latitude of the point
lon	number	Required	Longitude of the point

Example Response

200 OK

{
  "population": 1861599,
  "density_per_km2": 3599.4,
  "area_km2": 517,
  "area_name": "M.st.Warszawa",
  "year": 2023,
  "source": "gus_bdl"
}

Try in Playground →

GET/v1/hazards

Get natural hazard data for a location. In Poland, checks ISOK flood zone maps with return periods (10/100/500-year). Globally, returns empty result.

Parameters

Name	Type	Required	Description
lat	number	Required	Latitude of the point
lon	number	Required	Longitude of the point

Example Response

200 OK

{
  "in_flood_zone": true,
  "flood_zones": [
    {
      "return_period_years": 10,
      "scenario": "scenariusz Q 10%",
      "hazard_type": "fluvial"
    },
    {
      "return_period_years": 100,
      "scenario": "scenariusz Q 1%",
      "hazard_type": "fluvial"
    },
    {
      "return_period_years": 500,
      "scenario": "scenariusz Q 0,2%",
      "hazard_type": "fluvial"
    }
  ],
  "source": "isok"
}

Try in Playground →

POST/v1/geocode/batch

Batch geocode up to 100 addresses in a single request. Returns results for each address with status.

Parameters

Name	Type	Required	Description
addresses	array	Required	Array of objects with an "address" field

Example Response

200 OK

{
  "results": [
    {
      "address": "Warsaw, Poland",
      "status": "ok",
      "result": {
        "lat": 52.2298,
        "lng": 21.0118,
        "confidence": 0.8,
        "formatted_address": "Warszawa, Polska",
        "source": "openstreetmap",
        "components": {}
      }
    },
    {
      "address": "invalid xyz",
      "status": "not_found",
      "result": null,
      "error": "Address not found"
    }
  ],
  "total": 2,
  "successful": 1,
  "failed": 1
}

Try in Playground →

MCP Server

GeoResolver exposes all endpoints as tools via the Model Context Protocol (MCP), enabling AI agents to query spatial data directly.

Web (Streamable HTTP)

Connect to the hosted MCP server via Streamable HTTP. Pass your API key as a query parameter.

MCP Streamable HTTP

MCP endpoint: https://mcp.georesolver.com/mcp?api_key=gr_live_your_api_key

Use this URL in any MCP-compatible client (Claude Desktop, LangChain, custom agents). SSE is also available at /sse.

Local (stdio)

Run the MCP server locally for development. Set your API key as an environment variable.

Local MCP

# Install
pip install georesolver-mcp

# Or run from source
GEORESOLVER_API_KEY=gr_live_your_key python -m api.mcp_server

Available Tools

Tool	Description
geocode	Convert an address into coordinates
reverse_geocode	Convert coordinates into an address
find_nearby	Find nearby POIs (schools, hospitals, parks, etc.)
get_land_use	Get land use classification for a location
get_buildings	Find buildings with type, area, and levels
get_elevation	Get elevation, slope, and aspect (1m LIDAR in Poland)
get_parcels	Get cadastral parcel data (Poland)
get_boundaries	Get administrative boundaries with official codes
get_demographics	Get population, density, and area statistics
get_hazards	Get flood zone data (ISOK in Poland)

Rate Limits

Rate limits are enforced per API key on a per-minute sliding window. When you exceed the limit, the API returns 429 with a Retry-After header indicating how many seconds to wait.

Plan	Requests/month	Rate Limit
Free	1,000	60/min
Pro	50,000	600/min

Error Codes

Errors are returned as JSON with a detail field describing what went wrong.

Status	Code	Description
400	invalid_request	Missing or invalid parameters
401	unauthorized	Invalid or missing API key
403	forbidden	API key has been revoked
404	not_found	Address or location not found
429	rate_limited	Rate limit exceeded — see Retry-After header
500	internal_error	Unexpected server error

Error Response Format

401 Unauthorized

{
  "detail": "Missing API key. Provide X-API-Key header or api_key query parameter."
}

Roadmap

Upcoming features and country-specific data expansions:

Live

Cadastral Parcels (Poland)

Parcel IDs, commune, county, voivodeship, and geometry from ULDK

Live

Administrative Boundaries

Global admin boundaries with TERYT codes (Poland) and ISO codes (worldwide)

Live

Demographics

Population, density, and area from GUS (Poland) and OSM (global)

Live

Flood Hazards (Poland)

ISOK flood zones with Q10/Q100/Q500 return periods

Planned

Self-Hosted Geocoding (Poland)

High-accuracy address lookup from PRG address registry

Planned

Python & JavaScript SDKs

Typed client libraries for easy integration

Planned

More Countries

Expanding parcels, demographics, and hazards to Germany, Czech Republic, and more EU countries