{
  "openapi": "3.1.0",
  "info": {
    "title": "Onde Viver Bem — dados abertos",
    "summary": "Indicative post-AGI quality-of-life ranking, as published on ondeviverbem.com.",
    "description": "API estática, só leitura, com as notas e métricas publicadas no Onde Viver Bem. As notas são editoriais e indicativas; cada métrica cita a fonte; estimativas vêm marcadas com o método e a base. Atualizado em 2026-11-18. Não cite uma versão interna do estudo — use só a data. Documentação humana: https://ondeviverbem.com/dados — English: https://ondeviverbem.com/en/data.",
    "version": "2026-11-18",
    "contact": {
      "name": "Onde Viver Bem",
      "email": "contato@ondeviverbem.com",
      "url": "https://ondeviverbem.com"
    },
    "license": {
      "name": "Uso com atribuição a Onde Viver Bem e às fontes de cada métrica",
      "url": "https://ondeviverbem.com/dados#licenca"
    }
  },
  "servers": [
    {
      "url": "https://ondeviverbem.com/api/v1",
      "description": "Arquivos estáticos no site"
    }
  ],
  "tags": [
    {
      "name": "cidades"
    },
    {
      "name": "paises"
    },
    {
      "name": "bairros"
    }
  ],
  "paths": {
    "/cidades.json": {
      "get": {
        "tags": [
          "cidades"
        ],
        "summary": "Lista das cidades com score e métricas",
        "operationId": "listCidades",
        "responses": {
          "200": {
            "description": "Lista versionada pela data de atualização",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/cidades.csv": {
      "get": {
        "tags": [
          "cidades"
        ],
        "summary": "Mesma lista em CSV",
        "operationId": "listCidadesCsv",
        "responses": {
          "200": {
            "description": "CSV",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/cidades/{slug}.json": {
      "get": {
        "tags": [
          "cidades"
        ],
        "summary": "Ficha de uma cidade",
        "operationId": "getCidade",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "examples": [
                "es-malaga",
                "pt-porto"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Cidade",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Slug inexistente"
          }
        }
      }
    },
    "/paises.json": {
      "get": {
        "tags": [
          "paises"
        ],
        "summary": "Países com as cidades avaliadas e a posição no país e no ranking global",
        "operationId": "listPaises",
        "responses": {
          "200": {
            "description": "Países",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/bairros.json": {
      "get": {
        "tags": [
          "bairros"
        ],
        "summary": "Regiões dos mapas de bairros (e notas combinadas quando entram no ranking público)",
        "operationId": "listBairros",
        "responses": {
          "200": {
            "description": "Regiões",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "summary": "Este manifesto OpenAPI 3.1",
        "operationId": "getOpenapi",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Metrica": {
        "type": "object",
        "properties": {
          "valor": {},
          "unidade": {
            "type": "string",
            "nullable": true
          },
          "fonte": {
            "type": "object",
            "nullable": true
          },
          "estimado": {
            "type": "boolean"
          },
          "metodo": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "valor",
          "estimado"
        ]
      }
    }
  },
  "externalDocs": {
    "description": "Página para pessoas e agentes",
    "url": "https://ondeviverbem.com/dados"
  }
}
