{"openapi":"3.1.0","info":{"title":"Vizzie API","version":"1.0.0","description":"Open government data, boundaries and maps for AI agents and scripts. Free, no key; every answer carries the data's licence and a link into Vizzie. The same calls are offered as an MCP server at https://api.vizzie.org/mcp.","contact":{"email":"hello@vizzie.org","url":"https://www.vizzie.org/api/"}},"externalDocs":{"url":"https://www.vizzie.org/api/"},"servers":[{"url":"https://api.vizzie.org"}],"paths":{"/v1/datasets/search":{"post":{"operationId":"search_datasets","summary":"Find open datasets and census maps for a topic and place.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":200},"place":{"type":"string","minLength":1,"maxLength":200},"country":{"type":"string","pattern":"^[A-Za-z]{2}$"},"licence":{"default":"open","type":"string","enum":["open","any"]},"limit":{"default":10,"type":"integer","minimum":1,"maximum":50}},"required":["query"]}}}},"responses":{"200":{"description":"Results, census maps first, each with its licence and an open_url; plus search_url.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The request isn't valid — the message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited — see the limits in the docs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable — the answer includes a fallback link where there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/datasets/describe":{"get":{"operationId":"describe_dataset","summary":"A dataset's columns, licence and the boundaries it joins to.","parameters":[{"name":"ref","in":"query","required":true,"schema":{"type":"string"},"description":"A `ref` from search_datasets, unchanged."}],"responses":{"200":{"description":"The dataset and its columns; example values only under a servable licence.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The request isn't valid — the message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in Vizzie's catalogue.","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limited — see the limits in the docs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable — the answer includes a fallback link where there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/geography/resolve":{"post":{"operationId":"resolve_geography","summary":"Identify the boundary level and vintage of a column of area codes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"codes":{"minItems":1,"maxItems":5000,"type":"array","items":{"type":["string","number"]}},"country":{"type":"string","pattern":"^[A-Za-z]{2}$"},"column_name":{"type":"string","minLength":1,"maxLength":120}},"required":["codes"]}}}},"responses":{"200":{"description":"Candidate levels with the match rate over every distinct code, matched areas by name, and boundary availability.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The request isn't valid — the message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited — see the limits in the docs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable — the answer includes a fallback link where there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/boundaries":{"post":{"operationId":"get_boundaries","summary":"Boundary polygons as GeoJSON for codes or a bbox, licence-cleared levels only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string","pattern":"^[A-Za-z]{2,5}$"},"level":{"type":"string","minLength":1,"maxLength":40},"vintage":{"type":"integer","minimum":1900,"maximum":2100},"codes":{"minItems":1,"maxItems":2000,"type":"array","items":{"type":["string","number"]}},"bbox":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"items":false,"minItems":4,"maxItems":4},"detail":{"default":"medium","type":"string","enum":["low","medium","full"]}},"required":["country","level"]}}}},"responses":{"200":{"description":"A GeoJSON FeatureCollection with licence and attribution.","content":{"application/geo+json":{"schema":{"type":"object"}},"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The request isn't valid — the message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The level's licence doesn't allow passing the geometry on.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Vizzie doesn't hold that level.","content":{"application/json":{"schema":{"type":"object"}}}},"413":{"description":"Over 2,000 areas or the vertex budget.","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limited — see the limits in the docs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable — the answer includes a fallback link where there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/maps":{"post":{"operationId":"create_map","summary":"Make a map someone can open in Vizzie with one link.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"source":{"type":"string","const":"census"},"topic":{"type":"string","minLength":1,"maxLength":100},"place":{"type":"string","minLength":1,"maxLength":200},"country":{"type":"string","pattern":"^[A-Za-z]{2}$"},"level":{"type":"string","minLength":2,"maxLength":12}},"required":["source","topic"]},{"type":"object","properties":{"source":{"type":"string","const":"dataset"},"ref":{"type":"string","minLength":5,"maxLength":2000}},"required":["source","ref"]},{"type":"object","properties":{"source":{"type":"string","const":"rows"},"title":{"type":"string","minLength":1,"maxLength":120},"rows":{"minItems":1,"maxItems":5000,"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number","null"]}}},"code_column":{"type":"string","minLength":1,"maxLength":120},"value_column":{"type":"string","minLength":1,"maxLength":120},"geography":{"type":"object","properties":{"country":{"type":"string","pattern":"^[A-Za-z]{2,5}$"},"level":{"type":"string","minLength":1,"maxLength":40},"vintage":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["country","level"]},"style":{"type":"object","properties":{"ramp":{"type":"string","enum":["viridis","cividis","blues","greens","magma","cool-warm","blue-red","teal-brown"]},"classify":{"type":"string","enum":["continuous","natural-breaks","fixed"]},"classes":{"type":"integer","minimum":2,"maximum":10},"reverse":{"type":"boolean"}}}},"required":["source","title","rows","code_column","value_column"]}]}}}},"responses":{"200":{"description":"A census_link or dataset_link, with map_url.","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"A hosted map from your rows: map_url, the geography joined, the join counts and the boundaries' licence.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The request isn't valid — the message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The codes don't match a boundary level well enough to map.","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limited — see the limits in the docs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable — the answer includes a fallback link where there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string","description":"A plain-language explanation."}}},"next":{"type":"string","description":"What to do next."},"fallback_url":{"type":"string","format":"uri","description":"A Vizzie link to open instead, where there is one."}}}}}}