{
  "openapi": "3.1.0",
  "info": {
    "title": "Geoapify MCP Tool: Places: List Place Categories",
    "version": "1.1.0",
    "description": "AI-focused, tool-specific OpenAPI specification for list_place_categories 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": "callListPlaceCategories",
        "summary": "Places: List Place Categories",
        "description": "Use this zero-credit tool to discover the exact category value required by search_places. It accepts no arguments and returns category names only; use search_places afterward to find actual places.",
        "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/ListPlaceCategoriesToolCallRequest"
              },
              "examples": {
                "listPlaceCategoriesNumericId": {
                  "summary": "List place categories",
                  "description": "List the category values accepted by search_places.",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "tools/call",
                    "params": {
                      "name": "list_place_categories",
                      "arguments": {}
                    }
                  }
                },
                "listPlaceCategoriesStringId": {
                  "summary": "List categories with a string request id",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": "category-catalog",
                    "method": "tools/call",
                    "params": {
                      "name": "list_place_categories",
                      "arguments": {}
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response for the list_place_categories MCP tool. Tool execution and validation failures also use HTTP 200 with result.isError set to true.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListPlaceCategoriesToolCallResponse"
                },
                "examples": {
                  "listPlaceCategoriesSuccess": {
                    "summary": "Representative place category catalog",
                    "description": "Representative response containing 30 diverse categories. Call `list_place_categories` to retrieve the complete current catalog.",
                    "value": {
                      "jsonrpc": "2.0",
                      "id": 1,
                      "result": {
                        "content": [
                          {
                            "type": "text",
                            "text": "{\n  \"count\": 30,\n  \"categories\": [\n    \"accommodation.hotel\",\n    \"activity.sport_club\",\n    \"administrative.city_level\",\n    \"airport.international\",\n    \"amenity.drinking_water\",\n    \"beach.beach_resort\",\n    \"building.office\",\n    \"camping.camp_site\",\n    \"catering.restaurant\",\n    \"catering.cafe\",\n    \"commercial.supermarket\",\n    \"commercial.clothing\",\n    \"education.school\",\n    \"emergency.ambulance_station\",\n    \"entertainment.cinema\",\n    \"healthcare.hospital\",\n    \"leisure.park\",\n    \"natural.forest\",\n    \"office.company\",\n    \"parking\",\n    \"pet\",\n    \"populated_place.city\",\n    \"public_transport.bus\",\n    \"railway.train\",\n    \"rental.bicycle\",\n    \"service.financial\",\n    \"ski.lift\",\n    \"sport.swimming_pool\",\n    \"tourism.attraction\",\n    \"waterway.water_point\"\n  ]\n}"
                          }
                        ],
                        "structuredContent": {
                          "count": 30,
                          "categories": [
                            "accommodation.hotel",
                            "activity.sport_club",
                            "administrative.city_level",
                            "airport.international",
                            "amenity.drinking_water",
                            "beach.beach_resort",
                            "building.office",
                            "camping.camp_site",
                            "catering.restaurant",
                            "catering.cafe",
                            "commercial.supermarket",
                            "commercial.clothing",
                            "education.school",
                            "emergency.ambulance_station",
                            "entertainment.cinema",
                            "healthcare.hospital",
                            "leisure.park",
                            "natural.forest",
                            "office.company",
                            "parking",
                            "pet",
                            "populated_place.city",
                            "public_transport.bus",
                            "railway.train",
                            "rental.bicycle",
                            "service.financial",
                            "ski.lift",
                            "sport.swimming_pool",
                            "tourism.attraction",
                            "waterway.water_point"
                          ]
                        },
                        "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": "list_place_categories",
        "x-geoapify-mcp-input-schema": "#/components/schemas/ListPlaceCategoriesInput",
        "x-geoapify-mcp-output-schema": "#/components/schemas/ListPlaceCategoriesOutput"
      }
    }
  },
  "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."
          }
        }
      },
      "ListPlaceCategoriesInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {}
      },
      "ListPlaceCategoriesOutput": {
        "type": "object",
        "description": "Supported category catalog for search_places.",
        "required": [
          "count",
          "categories"
        ],
        "properties": {
          "count": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of category values returned."
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Exact category strings accepted by search_places."
          }
        }
      },
      "ListPlaceCategoriesToolCallParams": {
        "type": "object",
        "description": "MCP tools/call params for list_place_categories.",
        "additionalProperties": false,
        "required": [
          "name",
          "arguments"
        ],
        "properties": {
          "name": {
            "description": "Registered MCP tool name.",
            "const": "list_place_categories"
          },
          "arguments": {
            "description": "Arguments validated by the list_place_categories input schema.",
            "$ref": "#/components/schemas/ListPlaceCategoriesInput"
          }
        }
      },
      "ListPlaceCategoriesToolCallRequest": {
        "type": "object",
        "description": "JSON-RPC tools/call request for the list_place_categories 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 list_place_categories.",
            "$ref": "#/components/schemas/ListPlaceCategoriesToolCallParams"
          }
        },
        "examples": [
          {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {
              "name": "list_place_categories",
              "arguments": {}
            }
          },
          {
            "jsonrpc": "2.0",
            "id": "category-catalog",
            "method": "tools/call",
            "params": {
              "name": "list_place_categories",
              "arguments": {}
            }
          }
        ],
        "x-geoapify-mcp-tool": "list_place_categories",
        "x-geoapify-mcp-category": "Places",
        "x-geoapify-mcp-input-schema": "#/components/schemas/ListPlaceCategoriesInput",
        "x-geoapify-mcp-output-schema": "#/components/schemas/ListPlaceCategoriesOutput"
      },
      "ListPlaceCategoriesToolCallSuccessResponse": {
        "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/ListPlaceCategoriesOutput"
              },
              "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
              }
            }
          }
        }
      },
      "ListPlaceCategoriesToolCallResponse": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/ListPlaceCategoriesToolCallSuccessResponse"
          },
          {
            "$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": []
    }
  ]
}