{ "openapi": "3.1.0", "info": { "title": "Geoapify MCP Tool: Places: Search Places", "version": "1.1.0", "description": "AI-focused, tool-specific OpenAPI specification for search_places over the Geoapify JSON-RPC transport. Import this specification when an integration needs this tool without the full MCP catalog." }, "servers": [ { "url": "https://api.geoapify.com/v1", "description": "Default API endpoint." }, { "url": "https://api-eu.geoapify.com/v1", "description": "EU-focused endpoint. Geoapify service processing uses EU infrastructure." } ], "tags": [ { "name": "Places", "description": "Places MCP tools." } ], "paths": { "/mcp": { "post": { "tags": [ "Places" ], "operationId": "callSearchPlaces", "summary": "Places: Search Places", "description": "Use this tool to find places of one exact supported category around known coordinates. Call list_place_categories first when the category is unknown, and geocode an address first when the search center is not yet coordinates.", "parameters": [ { "name": "MCP-Protocol-Version", "in": "header", "required": false, "description": "Optional protocol version. Defaults to 2025-06-18 when omitted; explicitly unsupported versions are rejected.", "schema": { "type": "string", "enum": [ "2025-06-18" ] }, "example": "2025-06-18" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchPlacesToolCallRequest" }, "examples": { "searchPlacesRestaurants": { "summary": "Find nearby restaurants", "description": "Find places and points of interest by category near geographic coordinates.", "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "search_places", "arguments": { "category": "catering.restaurant", "lat": 52.52, "lon": 13.405, "radius_meters": 1000, "limit": 1, "lang": "en" } } } }, "searchPlacesSupermarkets": { "summary": "Find supermarkets within walking distance", "value": { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "search_places", "arguments": { "category": "commercial.supermarket", "lat": 48.8566, "lon": 2.3522, "radius_meters": 1000, "limit": 10, "lang": "fr" } } } }, "searchPlacesAttractions": { "summary": "Find tourist attractions", "value": { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "search_places", "arguments": { "category": "tourism.attraction", "lat": 51.5074, "lon": -0.1278, "radius_meters": 5000, "limit": 15, "lang": "en" } } } } } } } }, "responses": { "200": { "description": "JSON-RPC response for the search_places MCP tool. Tool execution and validation failures also use HTTP 200 with result.isError set to true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchPlacesToolCallResponse" }, "examples": { "searchPlacesSuccess": { "summary": "Nearby places result", "description": "Live response for the searchPlacesRestaurants request example.", "value": { "jsonrpc": "2.0", "id": 1, "result": { "content": [ { "type": "text", "text": "{\n \"category\": \"catering.restaurant\",\n \"coordinates\": {\n \"lat\": 52.52,\n \"lon\": 13.405\n },\n \"radius_meters\": 1000,\n \"count\": 1,\n \"results\": [\n {\n \"name\": \"BLOCK HOUSE\",\n \"country\": \"Germany\",\n \"country_code\": \"de\",\n \"city\": \"Berlin\",\n \"postcode\": \"10178\",\n \"district\": \"Mitte\",\n \"neighbourhood\": \"Nikolaiviertel\",\n \"suburb\": \"Mitte\",\n \"street\": \"Karl-Liebknecht-Straße\",\n \"housenumber\": \"7\",\n \"lon\": 13.4051631,\n \"lat\": 52.5205315,\n \"state\": \"Berlin\",\n \"state_code\": \"BE\",\n \"formatted\": \"BLOCK HOUSE, Karl-Liebknecht-Straße 7, 10178 Berlin, Germany\",\n \"categories\": [\n \"catering\",\n \"catering.restaurant\",\n \"catering.restaurant.steak_house\"\n ],\n \"datasource\": {\n \"sourcename\": \"openstreetmap\",\n \"attribution\": \"© OpenStreetMap contributors\",\n \"license\": \"Open Database License\",\n \"url\": \"https://www.openstreetmap.org/copyright\"\n },\n \"website\": \"http://www.block-house.de\",\n \"opening_hours\": \"Mo-Sa 12:00-23:00; Su 12:00-22:00\",\n \"brand\": \"BLOCK HOUSE\",\n \"brand_details\": {\n \"wikidata\": \"Q320430\",\n \"wikipedia\": \"de:Block House\"\n },\n \"name_international\": {\n \"de\": \"BLOCK HOUSE\"\n },\n \"contact\": {\n \"phone\": \"+49 30 2423300\"\n },\n \"facilities\": {\n \"wheelchair\": true,\n \"smoking\": true,\n \"toilets\": false,\n \"outdoor_seating\": true\n },\n \"catering\": {\n \"cuisine\": \"steak_house\"\n },\n \"distance\": 60,\n \"place_id\": \"518a17b08971cf2a4059d784b4c6a0424a40f00103f901bb70151a0000000092030b424c4f434b20484f555345\"\n }\n ]\n}" } ], "structuredContent": { "category": "catering.restaurant", "coordinates": { "lat": 52.52, "lon": 13.405 }, "radius_meters": 1000, "count": 1, "results": [ { "name": "BLOCK HOUSE", "country": "Germany", "country_code": "de", "city": "Berlin", "postcode": "10178", "district": "Mitte", "neighbourhood": "Nikolaiviertel", "suburb": "Mitte", "street": "Karl-Liebknecht-Straße", "housenumber": "7", "lon": 13.4051631, "lat": 52.5205315, "state": "Berlin", "state_code": "BE", "formatted": "BLOCK HOUSE, Karl-Liebknecht-Straße 7, 10178 Berlin, Germany", "categories": [ "catering", "catering.restaurant", "catering.restaurant.steak_house" ], "datasource": { "sourcename": "openstreetmap", "attribution": "© OpenStreetMap contributors", "license": "Open Database License", "url": "https://www.openstreetmap.org/copyright" }, "website": "http://www.block-house.de", "opening_hours": "Mo-Sa 12:00-23:00; Su 12:00-22:00", "brand": "BLOCK HOUSE", "brand_details": { "wikidata": "Q320430", "wikipedia": "de:Block House" }, "name_international": { "de": "BLOCK HOUSE" }, "contact": { "phone": "+49 30 2423300" }, "facilities": { "wheelchair": true, "smoking": true, "toilets": false, "outdoor_seating": true }, "catering": { "cuisine": "steak_house" }, "distance": 60, "place_id": "518a17b08971cf2a4059d784b4c6a0424a40f00103f901bb70151a0000000092030b424c4f434b20484f555345" } ] }, "isError": false } } } } } } }, "400": { "description": "Invalid HTTP request or unsupported MCP protocol version. Tool validation errors are returned with HTTP 200 and result.isError set to true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" }, "example": { "statusCode": 400, "error": "Bad Request", "message": "MCP-Protocol-Version header must be \"2025-06-18\"" } } } }, "401": { "description": "Missing or invalid Geoapify API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" }, "example": { "statusCode": 401, "error": "Unauthorized", "message": "Invalid apiKey" } } } }, "429": { "description": "Rate limit or quota exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" }, "example": { "statusCode": 429, "error": "Too Many Requests", "message": "Quota exceeded" } } } }, "500": { "description": "Internal gateway error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" }, "example": { "statusCode": 500, "error": "Internal Server Error", "message": "Request failed, please try again later" } } } } }, "x-geoapify-mcp-tool": "search_places", "x-geoapify-mcp-input-schema": "#/components/schemas/SearchPlacesInput", "x-geoapify-mcp-output-schema": "#/components/schemas/SearchPlacesOutput" } } }, "components": { "schemas": { "JsonRpcId": { "description": "JSON-RPC request identifier. The server echoes this value in the response.", "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "JsonRpcError": { "type": "object", "description": "JSON-RPC error object.", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "description": "JSON-RPC error code, such as -32600 for an invalid request, -32601 for an unknown method, or -32602 for invalid parameters." }, "message": { "type": "string", "description": "Human-readable JSON-RPC error message." }, "data": { "description": "Optional machine-readable error details." } } }, "JsonRpcErrorResponse": { "type": "object", "description": "JSON-RPC error response returned for invalid requests or unknown methods.", "required": [ "jsonrpc", "id", "error" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "$ref": "#/components/schemas/JsonRpcId" }, "error": { "$ref": "#/components/schemas/JsonRpcError" } } }, "GatewayError": { "type": "object", "description": "HTTP gateway error returned before or outside JSON-RPC tool execution.", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer", "description": "HTTP status code." }, "error": { "type": "string", "description": "HTTP error name." }, "message": { "type": "string", "description": "Human-readable error message." } } }, "SearchPlacesInput": { "type": "object", "additionalProperties": false, "required": [ "category", "lat", "lon" ], "properties": { "category": { "type": "string", "minLength": 3, "maxLength": 64, "pattern": "^[a-z0-9_-]+(?:\\.[a-z0-9_-]+)*$", "description": "Place category to find. Call list_place_categories first to get the supported category values." }, "lat": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude of the search center." }, "lon": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude of the search center." }, "radius_meters": { "type": "number", "minimum": 1, "description": "Optional search radius in meters. When omitted, returns the nearest matching places without a hard distance limit." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of places to return." }, "lang": { "type": "string", "default": "en", "description": "Result language as a supported two-letter language code." } } }, "SearchPlacesOutput": { "type": "object", "description": "Places matching one category around a coordinate.", "required": [ "category", "coordinates", "count", "results" ], "properties": { "category": { "type": "string", "description": "The supported place category used for this search." }, "coordinates": { "type": "object", "description": "Search center in latitude/longitude form.", "required": [ "lat", "lon" ], "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lon": { "type": "number", "minimum": -180, "maximum": 180 } } }, "radius_meters": { "type": "number", "description": "Applied search radius in meters when supplied." }, "count": { "type": "integer", "minimum": 0, "description": "Number of places returned." }, "results": { "type": "array", "items": { "type": "object", "description": "Public place properties after the MCP compact-output filters are applied.", "properties": { "name": { "type": "string" }, "continent": { "type": "string" }, "country": { "type": "string" }, "country_code": { "type": "string" }, "region": { "type": "string" }, "state": { "type": "string" }, "state_code": { "type": "string" }, "state_COG": { "type": "string" }, "department_COG": { "type": "string" }, "state_district": { "type": "string" }, "province": { "type": "string" }, "department": { "type": "string" }, "arrondissement": { "type": "string" }, "county": { "type": "string" }, "county_code": { "type": "string" }, "county_district": { "type": "string" }, "city": { "type": "string" }, "city_district": { "type": "string" }, "postcode": { "type": "string" }, "postal_code": { "type": "string" }, "openGeoDB:postal_codes": { "type": "string" }, "district": { "type": "string" }, "suburb": { "type": "string" }, "municipality": { "type": "string" }, "commune": { "type": "string" }, "subdistrict": { "type": "string" }, "city_block": { "type": "string" }, "neighbourhood": { "type": "string" }, "quarter": { "type": "string" }, "section": { "type": "string" }, "sector": { "type": "string" }, "subdivision": { "type": "string" }, "croft": { "type": "string" }, "allotments": { "type": "string" }, "residental": { "type": "string" }, "farm": { "type": "string" }, "farmyard": { "type": "string" }, "industrial": { "type": "string" }, "retail": { "type": "string" }, "borough": { "type": "string" }, "town": { "type": "string" }, "township": { "type": "string" }, "village": { "type": "string" }, "hamlet": { "type": "string" }, "locality": { "type": "string" }, "isolated_dwelling": { "type": "string" }, "street": { "type": "string" }, "road": { "type": "string" }, "footway": { "type": "string" }, "pedestrian": { "type": "string" }, "path": { "type": "string" }, "housenumber": { "type": "string" }, "house_number": { "type": "string" }, "house_name": { "type": "string" }, "old_name": { "type": "string" }, "other": { "type": "string" }, "formatted": { "type": "string" }, "unlocode": { "type": "string" }, "iso3166_sublevel": { "type": "string" }, "plus_code": { "type": "string" }, "plus_code_short": { "type": "string" }, "website": { "type": "string" }, "opening_hours": { "type": "string" }, "opening_hours_covid19": { "type": "string" }, "brand": { "type": "string" }, "operator": { "type": "string" }, "branch": { "type": "string" }, "network": { "type": "string" }, "owner": { "type": "string" }, "description": { "type": "string" }, "craft": { "type": "string" }, "ref": { "type": "string" }, "int_ref": { "type": "string" }, "ele": { "type": "string" }, "color": { "type": "string" }, "water_source": { "type": "string" }, "postcodes": { "type": "array", "items": { "type": "string" } }, "other_names": { "type": "object", "additionalProperties": { "type": "string" } }, "population": { "oneOf": [ { "type": "number" }, { "type": "object", "required": [ "actual", "by_years" ], "properties": { "actual": { "type": "string" }, "by_years": { "type": "object", "additionalProperties": { "type": "string" } } } } ] }, "lon": { "type": "number", "minimum": -180, "maximum": 180 }, "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "parent_as_place_id": { "type": "boolean" }, "timezone": { "type": "object", "required": [ "name", "offset_STD", "offset_DST", "offset_STD_seconds", "offset_DST_seconds" ], "properties": { "name": { "type": "string" }, "name_alt": { "type": "string" }, "country_codes": { "type": "array", "items": { "type": "string" } }, "offset_STD": { "type": "string" }, "offset_DST": { "type": "string" }, "offset_STD_seconds": { "type": "number" }, "offset_DST_seconds": { "type": "number" }, "abbreviation_STD": { "type": "string" }, "abbreviation_DST": { "type": "string" } } }, "website_other": { "type": "array", "items": { "type": "string" } }, "website_international": { "type": "object", "additionalProperties": { "type": "string" } }, "description_international": { "type": "object", "additionalProperties": { "type": "string" } }, "name_international": { "type": "object", "additionalProperties": { "type": "string" } }, "cuisine_international": { "type": "object", "additionalProperties": { "type": "string" } }, "ref_other": { "type": "object", "additionalProperties": { "type": "string" } }, "disused": { "type": "boolean" }, "commercial": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true } ] }, "payment_options": { "type": "object", "additionalProperties": { "type": "boolean" } }, "recycling_options": { "type": "object", "additionalProperties": { "type": "boolean" } }, "fuel_options": { "type": "object", "additionalProperties": { "type": "boolean" } }, "targeted_for": { "type": "object", "additionalProperties": { "type": "boolean" } }, "socket_options": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true } }, "distance": { "type": "number" }, "categories": { "type": "array", "items": { "type": "string" } }, "datasource": { "type": "object", "properties": { "sourcename": { "type": "string" }, "attribution": { "type": "string" }, "license": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "mappedTo": { "type": "object", "properties": { "lon": { "type": "number", "minimum": -180, "maximum": 180 }, "lat": { "type": "number", "minimum": -90, "maximum": 90 } } }, "place_id": { "type": "string", "minLength": 3, "maxLength": 2048 }, "brand_details": { "type": "object", "additionalProperties": true }, "operator_details": { "type": "object", "additionalProperties": true }, "network_details": { "type": "object", "additionalProperties": true }, "owner_details": { "type": "object", "additionalProperties": true }, "name_other": { "type": "object", "additionalProperties": true }, "contact": { "type": "object", "additionalProperties": true }, "facilities": { "type": "object", "additionalProperties": true }, "wiki_and_media": { "type": "object", "additionalProperties": true }, "historic": { "type": "object", "additionalProperties": true }, "heritage": { "type": "object", "additionalProperties": true }, "artwork": { "type": "object", "additionalProperties": true }, "accommodation": { "type": "object", "additionalProperties": true }, "catering": { "type": "object", "additionalProperties": true }, "parking": { "type": "object", "additionalProperties": true }, "airport": { "type": "object", "additionalProperties": true }, "power": { "type": "object", "additionalProperties": true }, "way": { "type": "object", "additionalProperties": true }, "building": { "type": "object", "additionalProperties": true }, "place_of_worship": { "type": "object", "additionalProperties": true }, "fire_hydrant": { "type": "object", "additionalProperties": true }, "defibrilator": { "type": "object", "additionalProperties": true }, "restrictions": { "type": "object", "additionalProperties": true }, "production": { "type": "object", "additionalProperties": true } } }, "description": "Matching places ordered by proximity and relevance." } } }, "SearchPlacesToolCallParams": { "type": "object", "description": "MCP tools/call params for search_places.", "additionalProperties": false, "required": [ "name", "arguments" ], "properties": { "name": { "description": "Registered MCP tool name.", "const": "search_places" }, "arguments": { "description": "Arguments validated by the search_places input schema.", "$ref": "#/components/schemas/SearchPlacesInput" } } }, "SearchPlacesToolCallRequest": { "type": "object", "description": "JSON-RPC tools/call request for the search_places MCP tool.", "additionalProperties": false, "required": [ "jsonrpc", "id", "method", "params" ], "properties": { "jsonrpc": { "description": "JSON-RPC protocol version.", "const": "2.0" }, "id": { "description": "Client-supplied JSON-RPC request id echoed in the response.", "$ref": "#/components/schemas/JsonRpcId" }, "method": { "description": "MCP method used to call a tool.", "const": "tools/call" }, "params": { "description": "Tool call parameters for search_places.", "$ref": "#/components/schemas/SearchPlacesToolCallParams" } }, "examples": [ { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "search_places", "arguments": { "category": "catering.restaurant", "lat": 52.52, "lon": 13.405, "radius_meters": 1000, "limit": 1, "lang": "en" } } }, { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "search_places", "arguments": { "category": "commercial.supermarket", "lat": 48.8566, "lon": 2.3522, "radius_meters": 1000, "limit": 10, "lang": "fr" } } }, { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "search_places", "arguments": { "category": "tourism.attraction", "lat": 51.5074, "lon": -0.1278, "radius_meters": 5000, "limit": 15, "lang": "en" } } } ], "x-geoapify-mcp-tool": "search_places", "x-geoapify-mcp-category": "Places", "x-geoapify-mcp-input-schema": "#/components/schemas/SearchPlacesInput", "x-geoapify-mcp-output-schema": "#/components/schemas/SearchPlacesOutput" }, "SearchPlacesToolCallSuccessResponse": { "type": "object", "description": "Successful JSON-RPC response with tool-specific structured content.", "required": [ "jsonrpc", "id", "result" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "$ref": "#/components/schemas/JsonRpcId" }, "result": { "type": "object", "required": [ "content", "structuredContent", "isError" ], "properties": { "content": { "type": "array", "description": "JSON text representation of structuredContent.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "const": "text" }, "text": { "type": "string", "description": "JSON-encoded copy of structuredContent." } } } }, "structuredContent": { "$ref": "#/components/schemas/SearchPlacesOutput" }, "isError": { "const": false } } } } }, "ToolCallErrorResponse": { "type": "object", "description": "JSON-RPC tools/call response when tool execution fails.", "required": [ "jsonrpc", "id", "result" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "$ref": "#/components/schemas/JsonRpcId" }, "result": { "type": "object", "required": [ "content", "isError" ], "properties": { "content": { "type": "array", "description": "Tool error details represented as JSON text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "const": "text" }, "text": { "type": "string", "description": "JSON-encoded GatewayError with statusCode, error, and message fields." } } } }, "isError": { "const": true } } } } }, "SearchPlacesToolCallResponse": { "oneOf": [ { "$ref": "#/components/schemas/SearchPlacesToolCallSuccessResponse" }, { "$ref": "#/components/schemas/ToolCallErrorResponse" }, { "$ref": "#/components/schemas/JsonRpcErrorResponse" } ] } }, "securitySchemes": { "ApiKeyInHeader": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Geoapify API key header. Recommended authentication method for MCP clients." } } }, "x-geoapify-mcp-tool-index": "index.json", "security": [ { "ApiKeyInHeader": [] } ] }