{ "openapi": "3.1.0", "info": { "title": "Geoapify Static Maps API", "version": "0.1.0", "description": "OpenAPI specification for rendering static map images." }, "servers": [ { "url": "https://api.geoapify.com/v1" } ], "tags": [ { "name": "Static Maps", "description": "Render static map images with markers, geometries, and GeoJSON overlays." } ], "paths": { "/staticmap": { "get": { "tags": [ "Static Maps" ], "operationId": "getStaticMap", "summary": "Render a static map with query parameters", "description": "Render a static map image. At least one viewport or overlay parameter is required: area, center, marker, geometry, or geojson.", "parameters": [ { "name": "apiKey", "in": "query", "required": true, "description": "Geoapify API key.", "schema": { "type": "string" }, "example": "YOUR_API_KEY" }, { "name": "style", "in": "query", "required": false, "description": "Map style.", "schema": { "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", "vector" ], "default": "osm-carto" } }, { "name": "area", "in": "query", "required": false, "description": "Map bounding box as rect:lon1,lat1,lon2,lat2.", "schema": { "type": "string", "pattern": "^rect:-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?$" }, "example": "rect:13.0884,52.3383,13.7611,52.6755" }, { "name": "center", "in": "query", "required": false, "description": "Map center as lonlat:lon,lat.", "schema": { "type": "string", "pattern": "^lonlat:-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?$" }, "example": "lonlat:13.405,52.52" }, { "name": "zoom", "in": "query", "required": false, "description": "Map zoom level.", "schema": { "type": "number", "minimum": 0, "maximum": 20, "default": 17 } }, { "name": "bearing", "in": "query", "required": false, "description": "Map rotation in degrees.", "schema": { "type": "number", "minimum": 0, "maximum": 360, "default": 0 } }, { "name": "pitch", "in": "query", "required": false, "description": "Map pitch in degrees.", "schema": { "type": "number", "minimum": 0, "maximum": 60, "default": 0 } }, { "name": "width", "in": "query", "required": false, "description": "Image width in pixels.", "schema": { "type": "integer", "minimum": 10, "maximum": 8192, "default": 1024 } }, { "name": "height", "in": "query", "required": false, "description": "Image height in pixels.", "schema": { "type": "integer", "minimum": 10, "maximum": 8192, "default": 768 } }, { "name": "scaleFactor", "in": "query", "required": false, "description": "Image scale factor.", "schema": { "type": "integer", "minimum": 1, "maximum": 9 } }, { "name": "format", "in": "query", "required": false, "description": "Output image format.", "schema": { "type": "string", "enum": [ "png", "jpeg" ], "default": "jpeg" } }, { "name": "marker", "in": "query", "required": false, "description": "Marker definitions. Multiple markers can be repeated or separated with |.", "style": "pipeDelimited", "explode": false, "schema": { "type": "array", "maxItems": 100, "items": { "type": "string" } }, "example": [ "lonlat:13.405,52.52;color:%23ff5050;size:large" ] }, { "name": "geometry", "in": "query", "required": false, "description": "Geometry overlay definitions. Multiple geometries can be repeated or separated with |.", "style": "pipeDelimited", "explode": false, "schema": { "type": "array", "maxItems": 100, "items": { "type": "string" } }, "example": [ "circle:13.405,52.52,500;linecolor:%23ff6600;fillcolor:%236600ff" ] }, { "name": "geojson", "in": "query", "required": false, "description": "GeoJSON object encoded as a JSON string.", "schema": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "name": "styleCustomization", "in": "query", "required": false, "description": "Style customization expressions. Multiple values can be repeated or separated with |.", "style": "pipeDelimited", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "attribution", "in": "query", "required": false, "description": "Attribution rendering mode.", "schema": { "type": "string", "enum": [ "default", "mandatory", "none" ], "default": "default" } }, { "name": "lang", "in": "query", "required": false, "description": "Map label language.", "schema": { "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" ] }, "example": "en" } ], "responses": { "200": { "description": "Rendered static map image.", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "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." } } }, "post": { "tags": [ "Static Maps" ], "operationId": "postStaticMap", "summary": "Render a static map with JSON body", "description": "Render a static map image with structured marker, geometry, and GeoJSON parameters.", "parameters": [ { "name": "apiKey", "in": "query", "required": true, "description": "Geoapify API key.", "schema": { "type": "string" }, "example": "YOUR_API_KEY" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaticMapRequest" }, "example": { "style": "osm-carto", "center": { "lat": 52.52, "lon": 13.405 }, "zoom": 12, "width": 1024, "height": 768, "format": "jpeg", "markers": [ { "lat": 52.52, "lon": 13.405, "color": "#ff5050", "size": "large" } ] } } } }, "responses": { "200": { "description": "Rendered static map image.", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "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": { "StaticMapRequest": { "type": "object", "additionalProperties": false, "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", "vector" ], "default": "osm-carto" }, "styleCustomization": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "$ref": "#/components/schemas/StyleCustomization" } }, "area": { "$ref": "#/components/schemas/StaticMapArea" }, "center": { "$ref": "#/components/schemas/LatLon" }, "zoom": { "type": "number", "minimum": 0, "maximum": 20, "default": 17 }, "bearing": { "type": "number", "minimum": 0, "maximum": 360, "default": 0 }, "pitch": { "type": "number", "minimum": 0, "maximum": 60, "default": 0 }, "width": { "type": "integer", "minimum": 10, "maximum": 8192, "default": 1024 }, "height": { "type": "integer", "minimum": 10, "maximum": 8192, "default": 768 }, "scaleFactor": { "type": "integer", "minimum": 1, "maximum": 9 }, "format": { "type": "string", "enum": [ "png", "jpeg" ], "default": "jpeg" }, "markers": { "type": "array", "minItems": 0, "maxItems": 100, "items": { "$ref": "#/components/schemas/StaticMapMarker" } }, "geometries": { "type": "array", "minItems": 0, "maxItems": 100, "items": { "oneOf": [ { "$ref": "#/components/schemas/CircleGeometry" }, { "$ref": "#/components/schemas/RectGeometry" }, { "$ref": "#/components/schemas/PolylineGeometry" }, { "$ref": "#/components/schemas/EncodedPolyline5Geometry" }, { "$ref": "#/components/schemas/EncodedPolyline6Geometry" }, { "$ref": "#/components/schemas/PolygonGeometry" } ] } }, "geojson": { "type": "object", "additionalProperties": true, "description": "GeoJSON object." }, "attribution": { "type": "string", "enum": [ "default", "mandatory", "none" ], "default": "default" }, "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" ] } } }, "StaticMapArea": { "type": "object", "additionalProperties": false, "required": [ "type", "value" ], "properties": { "type": { "const": "rect" }, "value": { "$ref": "#/components/schemas/RectBounds" } } }, "RectBounds": { "type": "object", "additionalProperties": false, "required": [ "lat1", "lon1", "lat2", "lon2" ], "properties": { "lat1": { "type": "number", "minimum": -90, "maximum": 90 }, "lon1": { "type": "number", "minimum": -180, "maximum": 180 }, "lat2": { "type": "number", "minimum": -90, "maximum": 90 }, "lon2": { "type": "number", "minimum": -180, "maximum": 180 } } }, "LatLon": { "type": "object", "additionalProperties": false, "required": [ "lat", "lon" ], "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lon": { "type": "number", "minimum": -180, "maximum": 180 } } }, "StyleCustomization": { "type": "object", "additionalProperties": false, "required": [ "layer" ], "properties": { "layer": { "type": "string", "minLength": 1, "maxLength": 255 }, "color": { "type": "string", "minLength": 3, "maxLength": 10 }, "size": { "type": "number", "minimum": 0, "maximum": 999 } } }, "StaticMapMarker": { "type": "object", "additionalProperties": false, "required": [ "lat", "lon" ], "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lon": { "type": "number", "minimum": -180, "maximum": 180 }, "color": { "type": "string", "minLength": 3, "maxLength": 10, "default": "#ff5050" }, "type": { "type": "string", "enum": [ "material", "awesome", "circle", "plain" ], "default": "material" }, "size": { "oneOf": [ { "type": "string", "enum": [ "small", "medium", "large", "x-large", "xx-large" ] }, { "type": "integer", "minimum": 1, "maximum": 1000 } ] }, "iconsize": { "type": "string", "enum": [ "small", "medium", "large" ], "default": "medium" }, "contentsize": { "type": "integer", "minimum": 1, "maximum": 1000 }, "icontype": { "type": "string", "enum": [ "material", "awesome", "lucide" ], "default": "awesome" }, "icon": { "type": "string", "minLength": 1, "maxLength": 100 }, "text": { "type": "string", "minLength": 1, "maxLength": 100 }, "textsize": { "type": "string", "enum": [ "small", "medium", "large" ], "default": "medium" }, "whitecircle": { "type": "string", "enum": [ "yes", "no" ], "default": "yes" }, "shadow": { "type": "string", "enum": [ "yes", "no" ], "default": "yes" }, "shadowcolor": { "type": "string", "minLength": 3, "maxLength": 10 }, "contentcolor": { "type": "string", "minLength": 3, "maxLength": 10 }, "strokecolor": { "type": "string", "minLength": 3, "maxLength": 10 } } }, "GeometryStyle": { "type": "object", "additionalProperties": true, "properties": { "linecolor": { "type": "string", "minLength": 3, "maxLength": 10, "default": "#000000" }, "lineopacity": { "type": "number", "minimum": 0, "maximum": 1, "default": 1 }, "linewidth": { "type": "number", "minimum": 1, "maximum": 20, "default": 1 }, "linestyle": { "type": "string", "enum": [ "solid", "dotted", "dashed", "longdash" ], "default": "solid" }, "fillcolor": { "type": "string", "minLength": 3, "maxLength": 10, "default": "#000000" }, "fillopacity": { "type": "number", "minimum": 0, "maximum": 1, "default": 1 } } }, "CircleGeometry": { "allOf": [ { "$ref": "#/components/schemas/GeometryStyle" }, { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "const": "circle" }, "value": { "type": "object", "additionalProperties": false, "required": [ "lat", "lon", "radius" ], "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lon": { "type": "number", "minimum": -180, "maximum": 180 }, "radius": { "type": "number" } } } } } ] }, "RectGeometry": { "allOf": [ { "$ref": "#/components/schemas/GeometryStyle" }, { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "const": "rect" }, "value": { "$ref": "#/components/schemas/RectBounds" } } } ] }, "PolylineGeometry": { "allOf": [ { "$ref": "#/components/schemas/GeometryStyle" }, { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "const": "polyline" }, "value": { "type": "array", "maxItems": 1000, "items": { "$ref": "#/components/schemas/LatLon" } } } } ] }, "EncodedPolyline5Geometry": { "allOf": [ { "$ref": "#/components/schemas/GeometryStyle" }, { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "const": "polyline5" }, "value": { "type": "string", "minLength": 1, "maxLength": 10000 } } } ] }, "EncodedPolyline6Geometry": { "allOf": [ { "$ref": "#/components/schemas/GeometryStyle" }, { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "const": "polyline6" }, "value": { "type": "string", "minLength": 1, "maxLength": 10000 } } } ] }, "PolygonGeometry": { "allOf": [ { "$ref": "#/components/schemas/GeometryStyle" }, { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "const": "polygon" }, "value": { "type": "array", "maxItems": 1000, "items": { "$ref": "#/components/schemas/LatLon" } } } } ] } } } }