---
title: "Contar obras"
method: GET
path: "/api/v1/constructions/count"
tags: ["Obras (CNO)"]
---

# Contar obras

`GET /api/v1/constructions/count`

## Request

- Base URL: `https://app.oportunidados.com.br`
- URL: `https://app.oportunidados.com.br/api/v1/constructions/count`
- Auth: one of:
  - HTTP bearer
  - API key in query parameter `api_token`

Contagem de obras do CNO pelos filtros do `permit`. Sem `group_by`, a resposta é `{ filter, total }`. Com `group_by` da whitelist, a resposta é `{ filter, group_by, total, data }` e `data` vem ordenado por `count` decrescente. Em `cod_municipio`, o `code` da resposta é IBGE, embora o filtro `mun` use SIAFI.

Autenticação: `Authorization: Bearer <token_digest>` (preferida) ou query `api_token` (legado). Recusas 400/401/403/422/429/503 usam o JSON literal do controller e dos concerns.

Disponível conforme o plano (`api_search_enabled`). Cada chamada conta 1 na quota mensal. Limite de 30 chamadas por minuto por conta neste grupo de endpoints; `eligible` devolve até 1.000 CNPJs por página.

## Query parameters

- `api_token` string
- `uf` string[]
- `mun` string[]
- `mun_exclude` string[]
- `cep` string[]
- `situacao` string[]
- `destinacao` string[]
- `categoria` string[]
- `tipo_obra` string[]
- `tipo_responsavel` string[]
- `qualificacao_responsavel` string[]
- `ni_responsavel` string[]
- `cnae` string[]
- `cnae_responsavel` string[]
- `cno` string[]
- `data_inicio_interval` string[]
- `area_total_range` string[]
- `group_by` 'uf' | 'cod_municipio' | 'situacao' | 'tipo_responsavel' | 'qualificacao_responsavel' | 'data_inicio_year'

## Response `200`

sucesso

- union
  - object
    - `filter` object, required
      - `cno` string[]
      - `situacao` string[]
      - `mun` string[]
      - `mun_exclude` string[]
      - `cep` string[]
      - `uf` string[]
      - `area_total_range` string[]
      - `data_inicio_interval` string[]
      - `destinacao` string[]
      - `categoria` string[]
      - `tipo_obra` string[]
      - `qualificacao_responsavel` string[]
      - `tipo_responsavel` string[]
      - `ni_responsavel` string[]
      - `cnae` string[]
      - `cnae_responsavel` string[]
    - `total` integer, required
  - object
    - `filter` object, required
      - `cno` string[]
      - `situacao` string[]
      - `mun` string[]
      - `mun_exclude` string[]
      - `cep` string[]
      - `uf` string[]
      - `area_total_range` string[]
      - `data_inicio_interval` string[]
      - `destinacao` string[]
      - `categoria` string[]
      - `tipo_obra` string[]
      - `qualificacao_responsavel` string[]
      - `tipo_responsavel` string[]
      - `ni_responsavel` string[]
      - `cnae` string[]
      - `cnae_responsavel` string[]
    - `group_by` string, required
    - `total` integer, required
    - `data` object[], required
      - `code` union, required
        - string
        - integer
      - `label` union, required
        - string
        - integer
      - `count` integer, required

## Other responses

- `400`: group_by inválido
- `401`: não autorizado
- `403`: proibido
- `422`: combinação proibida
- `429`: muitas requisições
- `503`: manutenção do CNO ou timeout da consulta

---

[API](https://skmtc.dev/oportunidados/apis/api-de-dados-oportunidados-v1.md) · [All operations](https://skmtc.dev/oportunidados/apis/api-de-dados-oportunidados-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/oportunidados/apis/api-de-dados-oportunidados-v1/revisions/0af33d72cdb4?raw)