openapi: 3.2.0
info:
  title: PontoFato Buscar API
  version: 2d690e87
  description: 'Ponto e fato de um lugar no Brasil. Índice: GET /api/.'
servers:
- url: https://pontofato.com
tags:
- name: Buscar
paths:
  /api/buscar:
    get:
      operationId: buscar
      summary: Busca textual de logradouro (FTS5), com UF e cidade opcionais
      description: 'Devolve: { items[{cep,logradouro,numero,complemento,bairro,cidade,uf,lat,lon,ibge,especie,especie_label,tipo_edificacao,tipo_edificacao_codigo,estabelecimento,estabelecimentos,especies,setor,distrito,subdistrito,quadra,face,nv_geo,nv_geo_label,finalidade,indicador_estab,indicador_const,id_cnefe,tipo_logradouro,titulo_logradouro,nome_logradouro,modificador,unidades,complementos,_links,_origem}], total }'
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
        description: Termo com 3+ caracteres.
        example: paulista
      - name: uf
        in: query
        required: false
        schema:
          type: string
        description: Restringe a uma UF.
        example: SP
      - name: cidade
        in: query
        required: false
        schema:
          type: string
        description: Trecho do município.
      responses:
        '200':
          description: '{ items[{cep,logradouro,numero,complemento,bairro,cidade,uf,lat,lon,ibge,especie,especie_label,tipo_edificacao,tipo_edificacao_codigo,estabelecimento,estabelecimentos,especies,setor,distrito,subdistrito,quadra,face,nv_geo,nv_geo_label,finalidade,indicador_estab,indicador_const,id_cnefe,tipo_logradouro,titulo_logradouro,nome_logradouro,modificador,unidades,complementos,_links,_origem}], total }'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginaPonto'
        '400':
          description: Termo curto demais.
      tags:
      - Buscar
components:
  schemas:
    Ponto:
      type: object
      properties:
        cep:
          type: string
          description: CEP formatado da unidade ou do edifício.
          nullable: true
        logradouro:
          type: string
          description: Tipo + nome do logradouro, já juntados.
        numero:
          type: string
          description: Número no logradouro.
          nullable: true
        complemento:
          type: string
          description: Complementos do CNEFE, se houver.
          nullable: true
        bairro:
          type: string
          description: Localidade/bairro no cadastro.
        cidade:
          type: string
          description: Município IBGE.
        uf:
          type: string
          description: Sigla da unidade da federação.
        lat:
          type: number
          description: Latitude WGS84 do ponto.
          nullable: true
        lon:
          type: number
          description: Longitude WGS84 do ponto.
          nullable: true
        ibge:
          type: string
          description: Código IBGE do município.
          nullable: true
        especie:
          type: string
          description: Código da espécie CNEFE (`1`–`8`).
          nullable: true
        especie_label:
          type: string
          description: Rótulo IBGE da espécie.
          nullable: true
        tipo_edificacao:
          type: string
          description: Casa, apartamento, vila — `COD_TIPO_ESPECIE`.
          nullable: true
        tipo_edificacao_codigo:
          type: string
          description: Código `101`–`104`.
          nullable: true
        estabelecimento:
          type: string
          description: Nome do estabelecimento, quando a espécie tem.
          nullable: true
        estabelecimentos:
          type: array
          items:
            type: string
          description: Nomes distintos no edifício (amostra).
          nullable: true
        especies:
          type: array
          items:
            $ref: '#/components/schemas/EspecieContagem'
          description: Mistura de espécies neste logradouro+número.
          nullable: true
        setor:
          type: string
          description: Setor censitário.
          nullable: true
        distrito:
          type: string
          description: Código de distrito IBGE.
          nullable: true
        subdistrito:
          type: string
          description: Código de subdistrito IBGE.
          nullable: true
        quadra:
          type: string
          description: Número da quadra no setor.
          nullable: true
        face:
          type: string
          description: Número da face da quadra.
          nullable: true
        nv_geo:
          type: string
          description: Nível de geocodificação (`1`–`6`).
          nullable: true
        nv_geo_label:
          type: string
          description: O que o nível de geo significa.
          nullable: true
        finalidade:
          type: string
          description: Residencial, não residencial, misto ou indeterminado.
          nullable: true
        indicador_estab:
          type: string
          description: Único ou múltiplo estabelecimento no endereço.
          nullable: true
        indicador_const:
          type: string
          description: Único ou múltiplo em construção/reforma.
          nullable: true
        id_cnefe:
          type: string
          description: '`COD_UNICO_ENDERECO` da unidade (só no detalhe).'
          nullable: true
        tipo_logradouro:
          type: string
          description: Tipo (RUA, AVENIDA…).
          nullable: true
        titulo_logradouro:
          type: string
          description: Título (DOUTOR…), se houver.
          nullable: true
        nome_logradouro:
          type: string
          description: Nome do logradouro sem o tipo.
          nullable: true
        modificador:
          type: string
          description: Modificador do número (SN, KM…).
          nullable: true
        unidades:
          type: integer
          description: Quantas unidades CNEFE neste logradouro+número (apartamentos, salas).
        complementos:
          type: integer
          description: Complementos distintos no edifício.
          nullable: true
        _links:
          type: object
          description: '`unidades` absoluto para o detalhe paginado.'
          nullable: true
        _origem:
          type: string
          description: UF do sqlite que respondeu.
      required:
      - cep
      - logradouro
      - numero
      - complemento
      - bairro
      - cidade
      - uf
      - lat
      - lon
      - ibge
      - especie
      - especie_label
      - tipo_edificacao
      - tipo_edificacao_codigo
      - estabelecimento
      - estabelecimentos
      - especies
      - setor
      - distrito
      - subdistrito
      - quadra
      - face
      - nv_geo
      - nv_geo_label
      - finalidade
      - indicador_estab
      - indicador_const
      - id_cnefe
      - tipo_logradouro
      - titulo_logradouro
      - nome_logradouro
      - modificador
      - unidades
      - complementos
      - _links
      - _origem
      description: 'Um endereço CNEFE: número, coordenada IBGE e o fato que veio no CSV.'
    PaginaPonto:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Ponto'
          description: Resultados (teto 50).
        total:
          type: integer
          description: Quantos vieram nesta página.
      required:
      - items
      - total
      description: Lista paginada de pontos.
    EspecieContagem:
      type: object
      properties:
        codigo:
          type: string
          description: Código IBGE da espécie (`1`–`8`).
          nullable: true
        label:
          type: string
          description: 'Rótulo: domicílio particular, ensino, saúde…'
          nullable: true
        n:
          type: integer
          description: Quantas unidades nesta espécie.
      required:
      - codigo
      - label
      - n
      description: Quantas unidades CNEFE de uma espécie no recorte.