{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/geoapify/json-schema/geoapify-static-map-request-schema.json",
  "title": "StaticMapRequest",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/geoapify-static-maps-api-openapi.yml#/components/schemas/StaticMapRequest",
  "type": "object",
  "anyOf": [
    {
      "required": [
        "area"
      ]
    },
    {
      "required": [
        "center"
      ]
    },
    {
      "required": [
        "markers"
      ]
    },
    {
      "required": [
        "geometries"
      ]
    },
    {
      "required": [
        "geojson"
      ]
    }
  ],
  "properties": {
    "style": {
      "type": "string",
      "enum": [
        "osm-carto",
        "carto",
        "dark-matter",
        "klokantech-basic",
        "osm-bright",
        "toner",
        "toner-grey",
        "osm-liberty",
        "maptiler-3d",
        "positron",
        "dark-matter-brown",
        "dark-matter-dark-grey",
        "dark-matter-dark-purple",
        "dark-matter-purple-roads",
        "dark-matter-yellow-roads",
        "osm-bright-grey",
        "osm-bright-smooth",
        "positron-blue",
        "positron-red"
      ],
      "default": "osm-carto",
      "description": "Geoapify map style used to render the image."
    },
    "styleCustomization": {
      "type": "array",
      "minItems": 1,
      "maxItems": 1000,
      "description": "Map-layer color and size customizations.",
      "items": {
        "$ref": "#/$defs/StyleCustomization"
      }
    },
    "area": {
      "$ref": "#/$defs/StaticMapArea",
      "description": "Map bounding box. Alternative to center and zoom."
    },
    "center": {
      "$ref": "#/$defs/LatLon",
      "description": "Map center. Ignored when area is specified."
    },
    "zoom": {
      "type": "number",
      "minimum": 0,
      "maximum": 20,
      "default": 17,
      "description": "Map zoom level. Ignored when area is specified."
    },
    "bearing": {
      "type": "number",
      "minimum": 0,
      "maximum": 360,
      "default": 0,
      "description": "Clockwise map rotation in degrees."
    },
    "pitch": {
      "type": "number",
      "minimum": 0,
      "maximum": 60,
      "default": 0,
      "description": "Map tilt in degrees."
    },
    "width": {
      "type": "integer",
      "minimum": 10,
      "maximum": 8192,
      "default": 1024,
      "description": "Base image width in pixels. At scale factor 2, the maximum width is 4096."
    },
    "height": {
      "type": "integer",
      "minimum": 10,
      "maximum": 8192,
      "default": 768,
      "description": "Base image height in pixels. At scale factor 2, the maximum height is 4096."
    },
    "scaleFactor": {
      "type": "integer",
      "minimum": 1,
      "maximum": 2,
      "default": 1,
      "description": "Output pixel-density multiplier. The final image dimensions are `width × scaleFactor` by `height × scaleFactor`."
    },
    "format": {
      "type": "string",
      "enum": [
        "png",
        "jpeg"
      ],
      "default": "jpeg",
      "description": "Output image format. `jpeg` returns `image/jpeg`; `png` returns `image/png`."
    },
    "markers": {
      "type": "array",
      "minItems": 0,
      "maxItems": 150,
      "description": "Markers drawn over the map.",
      "items": {
        "$ref": "#/$defs/StaticMapMarker"
      }
    },
    "geometries": {
      "type": "array",
      "minItems": 0,
      "maxItems": 100,
      "description": "Styled geometry overlays drawn over the map.",
      "items": {
        "oneOf": [
          {
            "$ref": "#/$defs/CircleGeometry"
          },
          {
            "$ref": "#/$defs/RectGeometry"
          },
          {
            "$ref": "#/$defs/PolylineGeometry"
          },
          {
            "$ref": "#/$defs/EncodedPolyline5Geometry"
          },
          {
            "$ref": "#/$defs/EncodedPolyline6Geometry"
          },
          {
            "$ref": "#/$defs/PolygonGeometry"
          }
        ]
      }
    },
    "geojson": {
      "type": "object",
      "additionalProperties": true,
      "description": "GeoJSON object."
    },
    "attribution": {
      "type": "string",
      "enum": [
        "default",
        "mandatory",
        "none"
      ],
      "default": "default",
      "description": "Controls attribution displayed on the map image. `default` includes Geoapify branding and required data-provider attribution; `mandatory` includes only required data-provider attribution; `none` is available for white-label use on eligible paid plans. When attribution is not displayed on the image, all required data-provider attribution must be provided in another visible place associated with the map."
    },
    "lang": {
      "type": "string",
      "enum": [
        "ab",
        "aa",
        "af",
        "ak",
        "sq",
        "am",
        "ar",
        "an",
        "hy",
        "as",
        "av",
        "ae",
        "ay",
        "az",
        "bm",
        "ba",
        "eu",
        "be",
        "bn",
        "bh",
        "bi",
        "bs",
        "br",
        "bg",
        "my",
        "ca",
        "ch",
        "ce",
        "ny",
        "zh",
        "cv",
        "kw",
        "co",
        "cr",
        "hr",
        "cs",
        "da",
        "dv",
        "nl",
        "en",
        "eo",
        "et",
        "ee",
        "fo",
        "fj",
        "fi",
        "fr",
        "ff",
        "gl",
        "ka",
        "de",
        "el",
        "gn",
        "gu",
        "ht",
        "ha",
        "he",
        "hz",
        "hi",
        "ho",
        "hu",
        "ia",
        "id",
        "ie",
        "ga",
        "ig",
        "ik",
        "io",
        "is",
        "it",
        "iu",
        "ja",
        "jv",
        "kl",
        "kn",
        "kr",
        "ks",
        "kk",
        "km",
        "ki",
        "rw",
        "ky",
        "kv",
        "kg",
        "ko",
        "ku",
        "kj",
        "la",
        "lb",
        "lg",
        "li",
        "ln",
        "lo",
        "lt",
        "lu",
        "lv",
        "gv",
        "mk",
        "mg",
        "ms",
        "ml",
        "mt",
        "mi",
        "mr",
        "mh",
        "mn",
        "na",
        "nv",
        "nb",
        "nd",
        "ne",
        "ng",
        "nn",
        "no",
        "ii",
        "nr",
        "oc",
        "oj",
        "cu",
        "om",
        "or",
        "os",
        "pa",
        "pi",
        "fa",
        "pl",
        "ps",
        "pt",
        "qu",
        "rm",
        "rn",
        "ro",
        "ru",
        "sa",
        "sc",
        "sd",
        "se",
        "sm",
        "sg",
        "sr",
        "gd",
        "sn",
        "si",
        "sk",
        "sl",
        "so",
        "st",
        "es",
        "su",
        "sw",
        "ss",
        "sv",
        "ta",
        "te",
        "tg",
        "th",
        "ti",
        "bo",
        "tk",
        "tl",
        "tn",
        "to",
        "tr",
        "ts",
        "tt",
        "tw",
        "ty",
        "ug",
        "uk",
        "ur",
        "uz",
        "ve",
        "vi",
        "vo",
        "wa",
        "cy",
        "wo",
        "fy",
        "xh",
        "yi",
        "yo",
        "za"
      ],
      "description": "Language used for map labels."
    }
  },
  "$defs": {
    "CircleGeometry": {
      "allOf": [
        {
          "$ref": "#/$defs/GeometryStyle"
        },
        {
          "type": "object",
          "required": [
            "type",
            "value"
          ],
          "properties": {
            "type": {
              "const": "circle",
              "description": "Circle geometry."
            },
            "value": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "lat",
                "lon",
                "radius"
              ],
              "properties": {
                "lat": {
                  "type": "number",
                  "minimum": -90,
                  "maximum": 90,
                  "description": "Circle-center latitude in decimal degrees."
                },
                "lon": {
                  "type": "number",
                  "minimum": -180,
                  "maximum": 180,
                  "description": "Circle-center longitude in decimal degrees."
                },
                "radius": {
                  "type": "number",
                  "description": "Circle radius in meters."
                }
              }
            }
          }
        }
      ]
    },
    "EncodedPolyline5Geometry": {
      "allOf": [
        {
          "$ref": "#/$defs/GeometryStyle"
        },
        {
          "type": "object",
          "required": [
            "type",
            "value"
          ],
          "properties": {
            "type": {
              "const": "polyline5",
              "description": "Polyline encoded with precision 5."
            },
            "value": {
              "type": "string",
              "minLength": 1,
              "maxLength": 10000,
              "description": "Encoded polyline string with precision 5."
            }
          }
        }
      ]
    },
    "EncodedPolyline6Geometry": {
      "allOf": [
        {
          "$ref": "#/$defs/GeometryStyle"
        },
        {
          "type": "object",
          "required": [
            "type",
            "value"
          ],
          "properties": {
            "type": {
              "const": "polyline6",
              "description": "Polyline encoded with precision 6."
            },
            "value": {
              "type": "string",
              "minLength": 1,
              "maxLength": 10000,
              "description": "Encoded polyline string with precision 6."
            }
          }
        }
      ]
    },
    "GeometryStyle": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "linecolor": {
          "type": "string",
          "minLength": 3,
          "maxLength": 10,
          "default": "#000000",
          "description": "Geometry outline color."
        },
        "lineopacity": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "default": 1,
          "description": "Geometry outline opacity from 0 (transparent) to 1 (opaque)."
        },
        "linewidth": {
          "type": "number",
          "minimum": 1,
          "maximum": 20,
          "default": 1,
          "description": "Geometry outline width in pixels."
        },
        "linestyle": {
          "type": "string",
          "enum": [
            "solid",
            "dotted",
            "dashed",
            "longdash"
          ],
          "default": "solid",
          "description": "Geometry outline pattern."
        },
        "fillcolor": {
          "type": "string",
          "minLength": 3,
          "maxLength": 10,
          "default": "#000000",
          "description": "Geometry fill color."
        },
        "fillopacity": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "default": 1,
          "description": "Geometry fill opacity from 0 (transparent) to 1 (opaque)."
        }
      }
    },
    "LatLon": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "lat",
        "lon"
      ],
      "properties": {
        "lat": {
          "type": "number",
          "minimum": -90,
          "maximum": 90,
          "description": "Latitude in decimal degrees."
        },
        "lon": {
          "type": "number",
          "minimum": -180,
          "maximum": 180,
          "description": "Longitude in decimal degrees."
        }
      }
    },
    "PolygonGeometry": {
      "allOf": [
        {
          "$ref": "#/$defs/GeometryStyle"
        },
        {
          "type": "object",
          "required": [
            "type",
            "value"
          ],
          "properties": {
            "type": {
              "const": "polygon",
              "description": "Polygon geometry defined by coordinate objects."
            },
            "value": {
              "type": "array",
              "maxItems": 1000,
              "description": "Ordered polygon vertices. Each point uses explicit `lat` and `lon` properties. The renderer closes the polygon automatically.",
              "items": {
                "$ref": "#/$defs/LatLon"
              }
            }
          }
        }
      ]
    },
    "PolylineGeometry": {
      "allOf": [
        {
          "$ref": "#/$defs/GeometryStyle"
        },
        {
          "type": "object",
          "required": [
            "type",
            "value"
          ],
          "properties": {
            "type": {
              "const": "polyline",
              "description": "Polyline geometry defined by coordinate objects."
            },
            "value": {
              "type": "array",
              "maxItems": 1000,
              "description": "Ordered polyline points. Each point uses explicit `lat` and `lon` properties.",
              "items": {
                "$ref": "#/$defs/LatLon"
              }
            }
          }
        }
      ]
    },
    "RectBounds": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "lat1",
        "lon1",
        "lat2",
        "lon2"
      ],
      "properties": {
        "lat1": {
          "type": "number",
          "minimum": -90,
          "maximum": 90,
          "description": "Latitude of the first bounding-box corner."
        },
        "lon1": {
          "type": "number",
          "minimum": -180,
          "maximum": 180,
          "description": "Longitude of the first bounding-box corner."
        },
        "lat2": {
          "type": "number",
          "minimum": -90,
          "maximum": 90,
          "description": "Latitude of the opposite bounding-box corner."
        },
        "lon2": {
          "type": "number",
          "minimum": -180,
          "maximum": 180,
          "description": "Longitude of the opposite bounding-box corner."
        }
      }
    },
    "RectGeometry": {
      "allOf": [
        {
          "$ref": "#/$defs/GeometryStyle"
        },
        {
          "type": "object",
          "required": [
            "type",
            "value"
          ],
          "properties": {
            "type": {
              "const": "rect",
              "description": "Rectangular bounding-box geometry."
            },
            "value": {
              "$ref": "#/$defs/RectBounds",
              "description": "Rectangle corners."
            }
          }
        }
      ]
    },
    "StaticMapArea": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "value"
      ],
      "properties": {
        "type": {
          "const": "rect"
        },
        "value": {
          "$ref": "#/$defs/RectBounds"
        }
      }
    },
    "StaticMapMarker": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "lat",
        "lon"
      ],
      "properties": {
        "lat": {
          "type": "number",
          "minimum": -90,
          "maximum": 90,
          "description": "Marker latitude in decimal degrees."
        },
        "lon": {
          "type": "number",
          "minimum": -180,
          "maximum": 180,
          "description": "Marker longitude in decimal degrees."
        },
        "color": {
          "type": "string",
          "minLength": 3,
          "maxLength": 10,
          "default": "#ff5050",
          "description": "Primary marker color as a CSS color name or hexadecimal value."
        },
        "type": {
          "type": "string",
          "enum": [
            "material",
            "awesome",
            "circle",
            "plain"
          ],
          "default": "material",
          "description": "Marker design. This is separate from `icontype`, which selects the icon library."
        },
        "size": {
          "oneOf": [
            {
              "type": "string",
              "enum": [
                "small",
                "medium",
                "large",
                "x-large",
                "xx-large"
              ]
            },
            {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000
            }
          ],
          "description": "Overall marker size as a named preset or pixel value."
        },
        "iconsize": {
          "type": "string",
          "enum": [
            "small",
            "medium",
            "large"
          ],
          "default": "medium",
          "description": "Named size of the icon inside the marker."
        },
        "contentsize": {
          "type": "integer",
          "minimum": 1,
          "maximum": 1000,
          "description": "Icon or text content size in pixels."
        },
        "icontype": {
          "type": "string",
          "enum": [
            "material",
            "awesome",
            "lucide"
          ],
          "default": "awesome",
          "description": "Icon library used to resolve the `icon` name."
        },
        "icon": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "description": "Icon name from the library selected by `icontype`."
        },
        "text": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "description": "Text displayed inside the marker instead of an icon."
        },
        "textsize": {
          "type": "string",
          "enum": [
            "small",
            "medium",
            "large"
          ],
          "default": "medium",
          "description": "Named text size inside the marker."
        },
        "whitecircle": {
          "type": "string",
          "enum": [
            "yes",
            "no"
          ],
          "default": "yes",
          "description": "Set to `no` to remove the white circle behind marker content."
        },
        "shadow": {
          "type": "string",
          "enum": [
            "yes",
            "no"
          ],
          "default": "yes",
          "description": "Set to `no` to remove the marker shadow."
        },
        "shadowcolor": {
          "type": "string",
          "minLength": 3,
          "maxLength": 10,
          "description": "Marker shadow color."
        },
        "contentcolor": {
          "type": "string",
          "minLength": 3,
          "maxLength": 10,
          "description": "Icon or text color inside the marker."
        },
        "strokecolor": {
          "type": "string",
          "minLength": 3,
          "maxLength": 10,
          "description": "Marker outline color."
        }
      }
    },
    "StyleCustomization": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "layer"
      ],
      "properties": {
        "layer": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "description": "Map style layer ID to customize."
        },
        "color": {
          "type": "string",
          "minLength": 3,
          "maxLength": 10,
          "description": "Replacement layer color as a CSS color name or hexadecimal value."
        },
        "size": {
          "type": "number",
          "minimum": 0,
          "maximum": 999,
          "description": "Replacement layer size."
        }
      }
    }
  }
}