{
  "openapi": "3.1.0",
  "info": {
    "title": "atlashot map rendering API",
    "version": "1",
    "description": "data on maps, from a link — GET /m renders {region: value} data as a choropleth map image. No auth, no request body: the URL is the entire request. Region codes: ISO 3166-1 alpha-2 (countries) / ISO 3166-2 (subdivisions); per-map code tables at /docs/maps/{id}.md. Full docs: /llms.txt"
  },
  "servers": [
    {
      "url": "https://atlashot.pages.dev"
    }
  ],
  "paths": {
    "/m": {
      "get": {
        "operationId": "renderMap",
        "summary": "Render a choropleth map from query parameters",
        "description": "Default response is the HTML viewer (for humans). format=svg returns the map itself as image/svg+xml (directly embeddable). format=json returns a machine-readable diagnostics report for the URL. Example: /m?map=europe&d=DE:83.2,FR:68.6&title=Population&format=svg",
        "parameters": [
          {
            "name": "map",
            "in": "query",
            "required": true,
            "description": "Which map to draw. Allowed: a map set id from the table below (e.g. world, europe, us, ro). Default: —.",
            "schema": {
              "type": "string",
              "enum": [
                "world",
                "europe",
                "us",
                "ro"
              ]
            }
          },
          {
            "name": "d",
            "in": "query",
            "required": true,
            "description": "The data. CODE is ISO 3166-1 alpha-2 for countries (DE, FR) or ISO 3166-2 for subdivisions (US-CA, RO-CJ). Values: numbers for color scales, or short text labels for categorical maps. Aliases accepted per map set: plain region names everywhere; ISO alpha-3 + ISO numeric (world, europe); EL/UK NUTS-0 (europe); FIPS numeric + bare postal (us); NUTS-3 codes + bare county codes (ro). Allowed: comma-separated CODE:value pairs. Default: —.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "title",
            "in": "query",
            "required": false,
            "description": "Map title, rendered into the image. Allowed: any text (URL-encoded, + for space). Default: none.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "subtitle",
            "in": "query",
            "required": false,
            "description": "Smaller line under the title. Allowed: any text. Default: none.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "unit",
            "in": "query",
            "required": false,
            "description": "Unit label shown with the legend (e.g. EUR/MWh, %). Allowed: any short text. Default: none.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "source",
            "in": "query",
            "required": false,
            "description": "Data source credit, rendered next to the attribution. Allowed: any short text. Default: none.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "palette",
            "in": "query",
            "required": false,
            "description": "Color palette. Sequential for all-positive numbers, diverging (rdbu/brbg/puor) for mixed-sign, tableau for categories. Allowed: blues, greens, oranges, purples, reds, viridis, rdbu, brbg, puor, tableau. Default: blues (numeric), rdbu (mixed-sign), tableau (text).",
            "schema": {
              "type": "string",
              "enum": [
                "blues",
                "greens",
                "oranges",
                "purples",
                "reds",
                "viridis",
                "rdbu",
                "brbg",
                "puor",
                "tableau"
              ]
            }
          },
          {
            "name": "scale",
            "in": "query",
            "required": false,
            "description": "How values map to color classes. threshold takes explicit cut points. Allowed: quantile, quantize, linear, threshold:10,20,50. Default: quantile (quantize over a symmetric domain for mixed-sign data).",
            "schema": {
              "type": "string",
              "pattern": "^(quantile|quantize|linear|threshold:-?[0-9.]+(,-?[0-9.]+)*)$"
            }
          },
          {
            "name": "classes",
            "in": "query",
            "required": false,
            "description": "Number of color classes. Allowed: 3–9. Default: 5.",
            "schema": {
              "type": "integer",
              "minimum": 3,
              "maximum": 9
            }
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "description": "Override the scale extent. Allowed: min,max (two numbers). Default: data min,max (symmetric around 0 for mixed-sign data).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "Number format for legend labels. Reserved values change the response instead: format=json returns machine-readable diagnostics (application/json); format=svg returns the map itself as a raw SVG image (image/svg+xml), directly embeddable in <img> tags. Allowed: a d3-format specifier (.1f, .0%, ~s) — or the reserved values json and svg. Default: ,.2~f.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "embed",
            "in": "query",
            "required": false,
            "description": "Render only the map (for iframes) — no page chrome. Allowed: 1. Default: 0.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          },
          {
            "name": "v",
            "in": "query",
            "required": false,
            "description": "URL format version. Allowed: 1. Default: 1.",
            "schema": {
              "type": "integer",
              "enum": [
                1
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Rendered map (HTML viewer or raw SVG) or diagnostics report (format=json); unmatched data rows degrade to warnings inside the report/banner, never a hard failure.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              },
              "image/svg+xml": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DiagnosticsReport"
                }
              }
            }
          },
          "400": {
            "description": "Required parameters missing or wrong (no/unknown map, missing d) — only with format=json or format=svg; the body is the diagnostics report.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DiagnosticsReport"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DiagnosticsReport": {
        "type": "object",
        "required": [
          "ok",
          "map",
          "matched",
          "total",
          "unmatched",
          "errors",
          "warnings",
          "fix",
          "example",
          "docs_url"
        ],
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "map": {
            "type": [
              "string",
              "null"
            ]
          },
          "matched": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "unmatched": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "input"
              ],
              "properties": {
                "input": {
                  "type": "string"
                },
                "suggestion": {
                  "type": "string"
                }
              }
            }
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "fix": {
            "type": [
              "string",
              "null"
            ]
          },
          "example": {
            "type": "string"
          },
          "docs_url": {
            "type": "string"
          }
        }
      }
    }
  }
}