Mapsource OpenStreetMap & Geospatial APIs

geo_search

Read-only

Search places and retrieve geographic entities. Use lookup for local address, business, brand and landmark search with soft map-focus bias, strict house numbers, source IDs and ambiguity reporting. Use discover for POIs in a viewport, polygon or isochrone, optionally ranked by travel time. Other operations: search, autocomplete, nearby, reverse, details, geocode, resolve, entity. Requires a subscription key.

Input Schema

TableJSON Schema

Name	Required	Description
`q`	No	lookup: address/name text, 1–120 characters. discover: optional name/brand filter. search/autocomplete: populated-place name. geocode: compatibility provider query.
`lat`	No
`lon`	No
`bbox`	No	west,south,east,north. lookup: soft focus unless bounded is true. discover: required region boundary unless region or minutes is supplied.
`limit`	No
`osmId`	No	details only.
`types`	No	lookup: comma-separated address,business,landmark,street,place.
`offset`	No	discover: result page offset.
`radius`	No	Metres. Defaults to 500 for nearby and 150 for reverse.
`rankBy`	No	discover: travel_time compares the nearest 25 candidates.
`region`	No	discover: polygon GeoJSON or owned result handle; alternatively supply bbox or minutes.
`bounded`	No	lookup: explicitly restrict results to bbox.
`costing`	No
`minutes`	No	discover: generate an isochrone from lat/lon.
`osmType`	No	details only.
`category`	No	lookup/discover: business or POI category, such as coffee, pharmacy or restaurants. nearby: feature category, such as cafe, restaurant, hospital or park.
`entityId`	No	entity only: an id from resolve, beginning geo_.
`language`	No	lookup: preferred language, default en.
`operation`	Yes	lookup: local address, business and brand suggestions with soft map-focus bias. discover: businesses in a viewport, polygon or isochrone, optionally ranked by travel time. resolve: name to entity ID. entity: entity lookup. search: populated-place names. autocomplete: populated-place prefixes. nearby: radius search. reverse: coordinate lookup. details: OSM type and ID lookup. geocode: compatibility provider; use lookup for new integrations.
`placeClass`	No	search and autocomplete: restrict to one class of populated place.
`countrycodes`	No	lookup: comma-separated two-letter country filters.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedSep 14, 2026

changedInput schema / properties / bbox / description

Previous value: -"lookup: west,south,east,north; soft focus unless bounded is true."New value: +"west,south,east,north. lookup: soft focus unless bounded is true. discover: required region boundary unless region or minutes is supplied."

changedInput schema / properties / category / description

Previous value: -"nearby: feature category, such as cafe, restaurant, hospital, or park."New value: +"lookup/discover: business or POI category, such as coffee, pharmacy or restaurants. nearby: feature category, such as cafe, restaurant, hospital or park."

changedInput schema / properties / operation / description

Previous value: -"resolve: name to entity ID. entity: entity lookup. search: place-name search. autocomplete: prefix search. nearby: radius search. reverse: coordinate lookup. details: OSM type and ID lookup. geocode: address lookup."New value: +"lookup: local address, business and brand suggestions with soft map-focus bias. discover: businesses in a viewport, polygon or isochrone, optionally ranked by travel time. resolve: name to entity ID. entity: entity lookup. search: populated-place names. autocomplete: populated-place prefixes. nearby: radius search. reverse: coordinate lookup. details: OSM type and ID lookup. geocode: compatibility provider; use lookup for new integrations."

changedInput schema / properties / q / description

Previous value: -"search, autocomplete and geocode: the text to look up."New value: +"lookup: address/name text, 1–120 characters. discover: optional name/brand filter. search/autocomplete: populated-place name. geocode: compatibility provider query."

Changed11 schema fields changedSep 14, 2026

addedInput schema / properties / bbox

Added value: +{
+  "description": "lookup: west,south,east,north; soft focus unless bounded is true.",
+  "maxLength": 120,
+  "type": "string"
+}

addedInput schema / properties / bounded

Added value: +{
+  "description": "lookup: explicitly restrict results to bbox.",
+  "type": "boolean"
+}

addedInput schema / properties / costing

Added value: +{
+  "enum": [
+    "auto",
+    "bicycle",
+    "pedestrian",
+    "truck"
+  ],
+  "type": "string"
+}

addedInput schema / properties / countrycodes

Added value: +{
+  "description": "lookup: comma-separated two-letter country filters.",
+  "maxLength": 40,
+  "type": "string"
+}

addedInput schema / properties / language

Added value: +{
+  "description": "lookup: preferred language, default en.",
+  "maxLength": 12,
+  "type": "string"
+}

addedInput schema / properties / minutes

Added value: +{
+  "description": "discover: generate an isochrone from lat/lon.",
+  "maximum": 30,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / offset

Added value: +{
+  "description": "discover: result page offset.",
+  "maximum": 2000,
+  "minimum": 0,
+  "type": "integer"
+}

changedInput schema / properties / operation / enum

Previous value: -[
-  "search",
-  "autocomplete",
-  "nearby",
-  "reverse",
-  "details",
-  "geocode",
-  "resolve",
-  "entity"
-]New value: +[
+  "search",
+  "autocomplete",
+  "nearby",
+  "reverse",
+  "details",
+  "geocode",
+  "resolve",
+  "entity",
+  "lookup",
+  "discover"
+]

addedInput schema / properties / rankBy

Added value: +{
+  "description": "discover: travel_time compares the nearest 25 candidates.",
+  "enum": [
+    "distance",
+    "travel_time"
+  ],
+  "type": "string"
+}

addedInput schema / properties / region

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 120,
+      "type": "string"
+    },
+    {
+      "additionalProperties": {},
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    }
+  ],
+  "description": "discover: polygon GeoJSON or owned result handle; alternatively supply bbox or minutes."
+}

addedInput schema / properties / types

Added value: +{
+  "description": "lookup: comma-separated address,business,landmark,street,place.",
+  "maxLength": 100,
+  "type": "string"
+}

Changed2 schema fields changedSep 11, 2026

changedInput schema / properties / category / description

Previous value: -"nearby only. Read the list from the error message if you send an unknown one."New value: +"nearby: feature category, such as cafe, restaurant, hospital, or park."

changedInput schema / properties / operation / description

Previous value: -"resolve: turn a name into a stable entity id you can pass to routing, isochrones and analysis instead of carrying coordinates. entity: read one back by its id. search: find a place by name anywhere on Earth. autocomplete: the same, prefix-matched while typing. nearby: named features or a category within a radius. reverse: what is at this coordinate. details: one feature by OSM type and id. geocode: address lookup through the external geocoder."New value: +"resolve: name to entity ID. entity: entity lookup. search: place-name search. autocomplete: prefix search. nearby: radius search. reverse: coordinate lookup. details: OSM type and ID lookup. geocode: address lookup."

Changed3 schema fields changedSep 10, 2026

addedInput schema / properties / entityId

Added value: +{
+  "description": "entity only: an id from resolve, beginning geo_.",
+  "maxLength": 300,
+  "minLength": 4,
+  "type": "string"
+}

changedInput schema / properties / operation / description

Previous value: -"search: find a place by name anywhere on Earth. autocomplete: the same, prefix-matched while typing. nearby: named features or a category within a radius. reverse: what is at this coordinate. details: one feature by OSM type and id. geocode: address lookup through the external geocoder."New value: +"resolve: turn a name into a stable entity id you can pass to routing, isochrones and analysis instead of carrying coordinates. entity: read one back by its id. search: find a place by name anywhere on Earth. autocomplete: the same, prefix-matched while typing. nearby: named features or a category within a radius. reverse: what is at this coordinate. details: one feature by OSM type and id. geocode: address lookup through the external geocoder."

changedInput schema / properties / operation / enum

Previous value: -[
-  "search",
-  "autocomplete",
-  "nearby",
-  "reverse",
-  "details",
-  "geocode"
-]New value: +[
+  "search",
+  "autocomplete",
+  "nearby",
+  "reverse",
+  "details",
+  "geocode",
+  "resolve",
+  "entity"
+]

Changed5 schema fields changedSep 10, 2026

changedInput schema / properties / operation / description

Previous value: -"nearby: named features or a category within a radius. reverse: what is at this coordinate. details: one feature by OSM type and id. geocode: look up a place by name."New value: +"search: find a place by name anywhere on Earth. autocomplete: the same, prefix-matched while typing. nearby: named features or a category within a radius. reverse: what is at this coordinate. details: one feature by OSM type and id. geocode: address lookup through the external geocoder."

changedInput schema / properties / operation / enum

Previous value: -[
-  "nearby",
-  "reverse",
-  "details",
-  "geocode"
-]New value: +[
+  "search",
+  "autocomplete",
+  "nearby",
+  "reverse",
+  "details",
+  "geocode"
+]

addedInput schema / properties / placeClass

Added value: +{
+  "description": "search and autocomplete: restrict to one class of populated place.",
+  "enum": [
+    "city",
+    "town",
+    "village",
+    "suburb",
+    "neighbourhood",
+    "hamlet"
+  ],
+  "type": "string"
+}

changedInput schema / properties / q / description

Previous value: -"geocode only: the place or address text."New value: +"search, autocomplete and geocode: the text to look up."

changedInput schema / properties / q / minLength
```
Previous value: -2New value: +1
```

AddedSep 9, 2026

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint=true and destructiveHint=false annotations, the description adds useful behavioral detail: lookup has a 'soft map-focus bias, strict house numbers, source IDs and ambiguity reporting', discover can rank 'by travel time', and a subscription key is required. These are non-obvious traits an agent would not infer from the annotations alone. It does not cover pagination or rate limits, but with the annotation safety profile already stated, this is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact, front-loaded with the primary purpose, and each sentence earns its place. It groups lookup vs discover first, then enumerates the remaining operations and ends with the auth requirement. There is no fluff or repetition of schema data.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (21 parameters, 10 operations), the description covers the main operational split and the non-obvious auth requirement. The schema provides detailed parameter descriptions for the rest. It does not mention return format, but there is no output schema and the read-only nature is captured; the description is complete enough for an agent to select and correctly invoke the tool for common cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already covers 81% of parameters with descriptions, so the baseline is 3. The description enriches operation-level semantics (e.g., what lookup and discover use) and mentions behaviors like 'soft map-focus bias', but it does not add direct parameter-level meaning beyond the schema. The schema itself carries most of the parameter burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear verb and resource ('Search places and retrieve geographic entities') and then sharply distinguishes the two main modes, lookup and discover, with concrete examples. It also lists the remaining operations, making the tool's overall scope obvious to an agent choosing between geo_search and its geo-* siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use lookup for local address...' and 'Use discover for POIs...', giving clear context for the two primary operations. It also names all other operations and warns about the subscription key requirement. It does not provide when-not guidance or alternatives for the remaining operations, so it stops just short of full routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Mapsource OpenStreetMap & Geospatial APIs tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?