{
  "openapi": "3.1.0",
  "info": {
    "title": "Geoapify Map Marker API",
    "version": "0.1.0",
    "description": "OpenAPI specification for rendering map marker images."
  },
  "servers": [
    {
      "url": "https://api.geoapify.com/v2"
    }
  ],
  "tags": [
    {
      "name": "Map Marker",
      "description": "Render customizable map marker images."
    }
  ],
  "paths": {
    "/icon": {
      "get": {
        "tags": [
          "Map Marker"
        ],
        "operationId": "getMapMarker",
        "summary": "Render a map marker image",
        "description": "Render a PNG marker image with optional shape, icon, text, colors, and scaling parameters.",
        "parameters": [
          {
            "name": "apiKey",
            "in": "query",
            "required": true,
            "description": "Geoapify API key.",
            "schema": {
              "type": "string"
            },
            "example": "YOUR_API_KEY"
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Marker pin shape.",
            "schema": {
              "type": "string",
              "enum": [
                "material",
                "awesome",
                "circle",
                "plain"
              ],
              "default": "material"
            },
            "example": "material"
          },
          {
            "name": "iconType",
            "in": "query",
            "required": false,
            "description": "Icon set used for the marker symbol.",
            "schema": {
              "type": "string",
              "enum": [
                "material",
                "awesome",
                "lucide"
              ]
            },
            "example": "material"
          },
          {
            "name": "icon",
            "in": "query",
            "required": false,
            "description": "Icon name.",
            "schema": {
              "type": "string",
              "pattern": "^[\\w-]{1,100}$",
              "minLength": 1,
              "maxLength": 100
            },
            "example": "location_on"
          },
          {
            "name": "text",
            "in": "query",
            "required": false,
            "description": "Text rendered inside the marker.",
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "example": "A"
          },
          {
            "name": "size",
            "in": "query",
            "required": false,
            "description": "Marker size in pixels.",
            "schema": {
              "type": "number",
              "exclusiveMinimum": 0
            },
            "example": 48
          },
          {
            "name": "contentSize",
            "in": "query",
            "required": false,
            "description": "Icon or text content size in pixels.",
            "schema": {
              "type": "number",
              "exclusiveMinimum": 0
            },
            "example": 24
          },
          {
            "name": "scaleFactor",
            "in": "query",
            "required": false,
            "description": "Image scale factor.",
            "schema": {
              "type": "number",
              "minimum": 0.5,
              "maximum": 10
            },
            "example": 2
          },
          {
            "name": "color",
            "in": "query",
            "required": false,
            "description": "Marker background color.",
            "schema": {
              "$ref": "#/components/schemas/ColorValue"
            },
            "example": "#ff5050"
          },
          {
            "name": "strokeColor",
            "in": "query",
            "required": false,
            "description": "Marker stroke color.",
            "schema": {
              "$ref": "#/components/schemas/ColorValue"
            },
            "example": "#ffffff"
          },
          {
            "name": "shadowColor",
            "in": "query",
            "required": false,
            "description": "Marker shadow color.",
            "schema": {
              "$ref": "#/components/schemas/ColorValue"
            },
            "example": "#000000"
          },
          {
            "name": "contentColor",
            "in": "query",
            "required": false,
            "description": "Icon or text color.",
            "schema": {
              "$ref": "#/components/schemas/ColorValue"
            },
            "example": "#ffffff"
          },
          {
            "name": "noWhiteCircle",
            "in": "query",
            "required": false,
            "description": "Disable the white circle behind marker content.",
            "allowEmptyValue": true,
            "schema": {
              "$ref": "#/components/schemas/MarkerFlag"
            },
            "example": "1"
          },
          {
            "name": "noShadow",
            "in": "query",
            "required": false,
            "description": "Disable the marker shadow.",
            "allowEmptyValue": true,
            "schema": {
              "$ref": "#/components/schemas/MarkerFlag"
            },
            "example": "1"
          }
        ],
        "responses": {
          "200": {
            "description": "Rendered marker image.",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "304": {
            "description": "Image was not modified."
          },
          "400": {
            "description": "Invalid request."
          },
          "401": {
            "description": "Missing or invalid Geoapify API key."
          },
          "429": {
            "description": "Rate limit or quota exceeded."
          },
          "500": {
            "description": "Internal gateway error."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ColorValue": {
        "type": "string",
        "maxLength": 100,
        "description": "CSS-like color value. Hex, named colors, rgb(), and rgba() are accepted.",
        "pattern": "^(#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})|[a-zA-Z]{3,32}|rgba?\\([^)]{1,64}\\))$",
        "examples": [
          "#ff5050",
          "red",
          "rgb(255,80,80)",
          "rgba(255,80,80,0.8)"
        ]
      },
      "MarkerFlag": {
        "type": "string",
        "description": "Boolean-like marker flag. The parameter can also be sent without a value.",
        "enum": [
          "",
          "1",
          "true",
          "yes"
        ],
        "default": ""
      }
    }
  }
}