{
    "openapi": "3.1.0",
    "info": {
        "title": "BrasilAddress API",
        "description": "API de consulta de enderecos, CEP, autocomplete e geocodificacao.",
        "version": "1.1.0"
    },
    "servers": [
        {
            "url": "/",
            "description": "URL relativa da aplicacao; o portal usa BRASILADDRESS_API_PUBLIC_BASE_URL nos exemplos"
        }
    ],
    "paths": {
        "/api/v1/health": {
            "get": {
                "tags": [
                    "System"
                ],
                "summary": "Verifica a disponibilidade do servico",
                "description": "Endpoint publico para health checks. Nao consome quota.",
                "operationId": "getHealth",
                "responses": {
                    "200": {
                        "description": "Servico disponivel",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HealthResponse"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Servico indisponivel",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/api/v1/readiness": {
            "get": {
                "tags": [
                    "System"
                ],
                "summary": "Verifica a prontidao da base",
                "operationId": "getReadiness",
                "responses": {
                    "200": {
                        "description": "Base pronta",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ReadinessResponse"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Base nao pronta",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/api/v1/cep/{cep}": {
            "get": {
                "tags": [
                    "Addresses"
                ],
                "summary": "Consulta um CEP",
                "operationId": "getAddressByPostalCode",
                "parameters": [
                    {
                        "name": "cep",
                        "in": "path",
                        "description": "CEP canonico com oito digitos; a API tambem normaliza 00000-000",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^[0-9]{8}$"
                        },
                        "example": "01001000"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Registros associados ao CEP",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/AddressResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "API key ausente ou invalida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "CEP invalido",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Quota ou rate limit excedido",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/addresses/search": {
            "get": {
                "tags": [
                    "Addresses"
                ],
                "summary": "Busca enderecos por filtros",
                "operationId": "searchAddresses",
                "parameters": [
                    {
                        "name": "logradouro",
                        "in": "query",
                        "description": "Parte do nome do logradouro",
                        "schema": {
                            "type": "string"
                        },
                        "example": "Paulista"
                    },
                    {
                        "name": "bairro",
                        "in": "query",
                        "description": "Parte do nome do bairro",
                        "schema": {
                            "type": "string"
                        },
                        "example": "Bela Vista"
                    },
                    {
                        "name": "cidade",
                        "in": "query",
                        "description": "Parte do nome da cidade",
                        "schema": {
                            "type": "string"
                        },
                        "example": "Sao Paulo"
                    },
                    {
                        "name": "uf",
                        "in": "query",
                        "description": "Sigla da UF",
                        "schema": {
                            "type": "string",
                            "maxLength": 2,
                            "minLength": 2
                        },
                        "example": "SP"
                    },
                    {
                        "name": "municipio",
                        "in": "query",
                        "description": "Codigo IBGE do municipio",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 3550308
                    },
                    {
                        "name": "cep",
                        "in": "query",
                        "description": "CEP canonico com oito digitos; a API tambem normaliza 00000-000",
                        "schema": {
                            "type": "string",
                            "pattern": "^[0-9]{8}$"
                        },
                        "example": "01001000"
                    },
                    {
                        "name": "numero",
                        "in": "query",
                        "description": "Numero do endereco",
                        "schema": {
                            "type": "string"
                        },
                        "example": "100"
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 1,
                            "minimum": 1
                        },
                        "example": 1
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Backend limita a 100",
                        "schema": {
                            "type": "integer",
                            "default": 20,
                            "maximum": 100,
                            "minimum": 1
                        },
                        "example": 20
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Busca paginada",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/AddressResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "API key invalida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Quota ou rate limit excedido",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/enderecos": {
            "get": {
                "tags": [
                    "Addresses"
                ],
                "summary": "Alias em portugues para busca de enderecos",
                "operationId": "listAddresses",
                "parameters": [
                    {
                        "name": "logradouro",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "example": "Paulista"
                    },
                    {
                        "name": "bairro",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "example": "Bela Vista"
                    },
                    {
                        "name": "cidade",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "example": "Sao Paulo"
                    },
                    {
                        "name": "uf",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "maxLength": 2,
                            "minLength": 2
                        },
                        "example": "SP"
                    },
                    {
                        "name": "municipio",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 3550308
                    },
                    {
                        "name": "cep",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "pattern": "^[0-9]{8}$"
                        },
                        "example": "01001000"
                    },
                    {
                        "name": "numero",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "example": "100"
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 1,
                            "minimum": 1
                        },
                        "example": 1
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 20,
                            "maximum": 100,
                            "minimum": 1
                        },
                        "example": 20
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Busca paginada",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/AddressResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "API key invalida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Quota ou rate limit excedido",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/enderecos/busca": {
            "get": {
                "tags": [
                    "Addresses"
                ],
                "summary": "Busca textual de logradouro",
                "operationId": "searchAddressesText",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "description": "Termo de busca normalizado",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "minLength": 1
                        },
                        "example": "Avenida Paulista"
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 1,
                            "minimum": 1
                        },
                        "example": 1
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 20,
                            "maximum": 100,
                            "minimum": 1
                        },
                        "example": 20
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Busca paginada",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/AddressResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "API key invalida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Query invalida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Quota ou rate limit excedido",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/geocode": {
            "get": {
                "tags": [
                    "Geocoding"
                ],
                "summary": "Geocodifica um texto",
                "operationId": "geocodeAddress",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "description": "Consulta com pelo menos 3 caracteres",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "minLength": 3
                        },
                        "example": "Avenida Paulista Sao Paulo"
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 10,
                            "maximum": 50,
                            "minimum": 1
                        },
                        "example": 10
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Candidatos encontrados",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/AddressResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "API key invalida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Query invalida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Quota ou rate limit excedido",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/geocoding": {
            "get": {
                "tags": [
                    "Geocoding"
                ],
                "summary": "Alias de geocodificacao",
                "operationId": "geocodingAlias",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "minLength": 3
                        },
                        "example": "Avenida Paulista Sao Paulo"
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 10,
                            "maximum": 50,
                            "minimum": 1
                        },
                        "example": 10
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Candidatos encontrados",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/AddressResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "API key invalida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Query invalida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Quota ou rate limit excedido",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/autocomplete": {
            "get": {
                "tags": [
                    "Autocomplete"
                ],
                "summary": "Sugere logradouros por prefixo",
                "operationId": "autocompleteAddress",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "description": "Prefixo com pelo menos 2 caracteres",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "minLength": 2
                        },
                        "example": "Avenida Pau"
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 10,
                            "maximum": 50,
                            "minimum": 1
                        },
                        "example": 10
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Sugestoes encontradas",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/AutocompleteItem"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "API key invalida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Query invalida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Quota ou rate limit excedido",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/reverse": {
            "get": {
                "tags": [
                    "Geocoding"
                ],
                "summary": "Encontra enderecos proximos de coordenadas",
                "operationId": "reverseGeocode",
                "parameters": [
                    {
                        "name": "lat",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "number",
                            "format": "double",
                            "maximum": 6,
                            "minimum": -34
                        },
                        "example": -23.561684
                    },
                    {
                        "name": "lon",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "number",
                            "format": "double",
                            "maximum": -28,
                            "minimum": -74
                        },
                        "example": -46.655981
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 10,
                            "maximum": 50,
                            "minimum": 1
                        },
                        "example": 10
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Enderecos proximos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/AddressResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "API key invalida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Coordenadas invalidas",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Quota ou rate limit excedido",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/municipios": {
            "get": {
                "tags": [
                    "Geography"
                ],
                "summary": "Lista municipios",
                "operationId": "listMunicipalities",
                "parameters": [
                    {
                        "name": "uf",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "maxLength": 2,
                            "minLength": 2
                        },
                        "example": "SP"
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 1,
                            "minimum": 1
                        },
                        "example": 1
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Maximo de 100 registros por pagina",
                        "schema": {
                            "type": "integer",
                            "default": 100,
                            "maximum": 100,
                            "minimum": 1
                        },
                        "example": 100
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Municipios paginados",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Municipality"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "page": {
                                                    "type": "integer"
                                                },
                                                "limit": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "API key invalida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Quota ou rate limit excedido",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/municipios/{codigoIbge}": {
            "get": {
                "tags": [
                    "Geography"
                ],
                "summary": "Consulta municipio por codigo IBGE",
                "operationId": "getMunicipality",
                "parameters": [
                    {
                        "name": "codigoIbge",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "example": 3550308
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Municipio encontrado ou data vazia",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Municipality"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "API key invalida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Quota ou rate limit excedido",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/bairros": {
            "get": {
                "tags": [
                    "Geography"
                ],
                "summary": "Lista bairros de um municipio",
                "operationId": "listDistricts",
                "parameters": [
                    {
                        "name": "municipio",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "example": 3550308
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 1,
                            "minimum": 1
                        },
                        "example": 1
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Maximo de 100 registros por pagina",
                        "schema": {
                            "type": "integer",
                            "default": 100,
                            "maximum": 100,
                            "minimum": 1
                        },
                        "example": 100
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Bairros paginados",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/District"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "page": {
                                                    "type": "integer"
                                                },
                                                "limit": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "API key invalida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Quota ou rate limit excedido",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/logradouros": {
            "get": {
                "tags": [
                    "Geography"
                ],
                "summary": "Lista logradouros de um municipio",
                "operationId": "listStreets",
                "parameters": [
                    {
                        "name": "municipio",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "example": 3550308
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 1,
                            "minimum": 1
                        },
                        "example": 1
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Maximo de 100 registros por pagina",
                        "schema": {
                            "type": "integer",
                            "default": 100,
                            "maximum": 100,
                            "minimum": 1
                        },
                        "example": 100
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Logradouros paginados",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Street"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "page": {
                                                    "type": "integer"
                                                },
                                                "limit": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "API key invalida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Quota ou rate limit excedido",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "Address": {
                "properties": {
                    "street": {
                        "type": "string",
                        "example": "Praca da Se"
                    },
                    "district": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "Se"
                    },
                    "city": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "Sao Paulo"
                    },
                    "uf": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "SP",
                        "maxLength": 2,
                        "minLength": 2
                    },
                    "city_code": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "example": 3550308
                    },
                    "ibge_code": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "example": 3550308
                    },
                    "cep": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "pattern": "^[0-9]{8}$",
                        "example": "01001000"
                    },
                    "number": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "100"
                    },
                    "latitude": {
                        "type": [
                            "number",
                            "null"
                        ],
                        "format": "double"
                    },
                    "longitude": {
                        "type": [
                            "number",
                            "null"
                        ],
                        "format": "double"
                    },
                    "precision": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "address"
                    },
                    "source": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "base nacional"
                    },
                    "distance_km": {
                        "type": [
                            "number",
                            "null"
                        ],
                        "format": "double"
                    },
                    "confidence": {
                        "type": [
                            "number",
                            "null"
                        ],
                        "format": "double"
                    }
                },
                "type": "object"
            },
            "ErrorResponse": {
                "required": [
                    "error"
                ],
                "properties": {
                    "error": {
                        "required": [
                            "code",
                            "message"
                        ],
                        "properties": {
                            "code": {
                                "type": "string",
                                "example": "invalid_query"
                            },
                            "message": {
                                "type": "string",
                                "example": "q deve ter ao menos 3 caracteres."
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "AddressResponse": {
                "required": [
                    "data"
                ],
                "properties": {
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Address"
                        }
                    },
                    "meta": {
                        "type": "object",
                        "additionalProperties": true
                    }
                },
                "type": "object"
            },
            "HealthResponse": {
                "required": [
                    "status",
                    "service"
                ],
                "properties": {
                    "status": {
                        "type": "string",
                        "example": "ok",
                        "enum": [
                            "ok",
                            "error"
                        ]
                    },
                    "service": {
                        "type": "string",
                        "example": "BrasilAddress API"
                    }
                },
                "type": "object"
            },
            "ReadinessResponse": {
                "required": [
                    "status"
                ],
                "properties": {
                    "status": {
                        "type": "string",
                        "example": "ready",
                        "enum": [
                            "ready",
                            "not_ready"
                        ]
                    }
                },
                "type": "object"
            },
            "Municipality": {
                "properties": {
                    "name": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "Sao Paulo"
                    },
                    "ibge_code": {
                        "type": "integer",
                        "example": 3550308
                    },
                    "records": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "example": 120000
                    },
                    "uf": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "SP"
                    },
                    "state": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "Sao Paulo"
                    },
                    "latitude": {
                        "type": [
                            "number",
                            "null"
                        ]
                    },
                    "longitude": {
                        "type": [
                            "number",
                            "null"
                        ]
                    }
                },
                "type": "object"
            },
            "District": {
                "properties": {
                    "id": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "name": {
                        "type": "string",
                        "example": "Bela Vista"
                    },
                    "city": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "Sao Paulo"
                    },
                    "ibge_code": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "example": 3550308
                    }
                },
                "type": "object"
            },
            "Street": {
                "properties": {
                    "id": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "name": {
                        "type": "string",
                        "example": "Avenida Paulista"
                    },
                    "street_type": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "Avenida"
                    },
                    "district": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "Bela Vista"
                    },
                    "city": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "Sao Paulo"
                    },
                    "city_code": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "example": 3550308
                    }
                },
                "type": "object"
            },
            "AutocompleteItem": {
                "properties": {
                    "street": {
                        "type": "string",
                        "example": "Avenida Paulista"
                    },
                    "city": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "Sao Paulo"
                    },
                    "uf": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "SP"
                    },
                    "city_code": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "example": 3550308
                    },
                    "number": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "100"
                    }
                },
                "type": "object"
            }
        },
        "securitySchemes": {
            "ApiKey": {
                "type": "apiKey",
                "description": "Chave emitida pelo portal. Nunca publique a chave em codigo cliente.",
                "name": "X-API-Key",
                "in": "header"
            },
            "BearerApiKey": {
                "type": "http",
                "description": "A mesma API key pode ser enviada como Bearer token.",
                "scheme": "bearer"
            }
        }
    },
    "security": [
        {
            "ApiKey": []
        },
        {
            "BearerApiKey": []
        }
    ],
    "tags": [
        {
            "name": "System",
            "description": "System"
        },
        {
            "name": "Addresses",
            "description": "Addresses"
        },
        {
            "name": "Geocoding",
            "description": "Geocoding"
        },
        {
            "name": "Autocomplete",
            "description": "Autocomplete"
        },
        {
            "name": "Geography",
            "description": "Geography"
        }
    ]
}