# w14n.dev Data API — Comprehensive LLM Specification

> Canonical documentation for autonomous agents and developer tooling.
> Notice: All datasets are partial samples. No authentication is required. The API is free during the test period, may change.

---

## 1. Global Response Envelope

All API endpoints return JSON responses wrapped in a common metadata envelope.

```json
{
  "meta": {
    "api_version": "1",
    "dataset": "<dataset_identifier>",
    "data_as_of": "2026-08",
    "snapshot_note": "Compiled from Brazilian Federal Revenue (Receita Federal) open CNPJ data, July-August 2026 publications. Records that closed or changed after the snapshot may still appear as active.",
    "scope": "<scope_identifier>",
    "coverage": "partial_sample",
    "source": "Receita Federal do Brasil - CNPJ open data",
    "generated_at": "<ISO-8601 UTC timestamp>"
  },
  "data": {}
}
```

When an error occurs (HTTP 400, 404, 429), the response uses:
```json
{
  "error": {
    "code": "invalid_cnpj | invalid_param | not_in_sample | cnae_not_in_sample | state_not_in_sample | not_found | rate_limited",
    "message": "Human-readable explanation of error",
    "hint": "Actionable correction suggestion"
  },
  "meta": { ... }
}
```

---

## 2. Company Lookup Endpoint

- **Method**: `GET /api/v1/company/{cnpj}`
- **Path Parameter**: `cnpj` (14 digits, formatted or digits-only).
- **Scope**: Registered commercial entities in agribusiness, mining, and meat-processing sectors.
- **Example Response (excerpt)**:
```json
{
  "cnpj": "00043463000483",
  "legal_name": "MINERACAO CARAIBA S/A",
  "trade_name": "MINERACAO CARAIBA S/A",
  "status": "ATIVA",
  "capital_social": 331405051.0,
  "size": "DEMAIS",
  "primary_activity": {
    "code": "0724301",
    "text": "Extracao de minerio de cobre"
  },
  "address": {
    "city": "JAGUARARI",
    "state": "BA"
  }
}
```

---

## 3. CNAE Establishments by Municipality Endpoint

- **Method**: `GET /api/v1/analytics/cnae/{cnae}/municipalities?state={UF}`
- **Query Parameter**: `state` (Required, 2-letter uppercase UF, e.g. MT, SP).
- **Supported CNAEs**:
  - `0115600`: Cultivo de soja (Soybean)
  - `0134200`: Cultivo de cafe (Coffee)
  - `0710301`: Extracao de minerio de ferro (Iron ore)
  - `0710302`: Pelotizacao de minerio de ferro
  - `1011201`: Frigorifico - abate de bovinos (Beef)
  - `1012101`: Abate de aves (Poultry)
- **Response Shape**:
```json
{
  "cnae": "0115600",
  "state": "MT",
  "total_active_establishments_in_state": 1420,
  "municipalities": [
    {
      "municipality": "SORRISO",
      "ibge_code": "5107925",
      "active_establishments": 142,
      "size_mix": { "ME": 20, "EPP": 12, "DEMAIS": 110 },
      "age_mix": { "under_5y": 30, "5_to_10y": 45, "over_10y": 67 }
    }
  ]
}
```

---

## 4. CNAE State Totals Endpoint

- **Method**: `GET /api/v1/analytics/cnae/{cnae}/states`
- **Response**: List of all Brazilian states with active establishments for the given CNAE.

---

## 5. FIPE Vehicle Depreciation Endpoint

- **Method**: `GET /api/v1/fipe/{fipe_code}/depreciation`
- **Path Parameter**: `fipe_code` (e.g. 001001-4 or 0010014).
- **Scope**: Historical series 2001-01 to 2023-09.

---

## 6. Geographic Municipality Resolver Endpoint

- **Method**: `GET /api/v1/geo/municipality?name={name}&state={UF}`
- **Query Parameters**:
  - `name`: Municipality name or slug (e.g. "Sorriso", "plano-piloto", "brasilia").
  - `state`: 2-letter state code (e.g. "MT", "DF").
- **Response**: Matches with latitude, longitude, and IBGE code (or administrative region details).

---

## 7. Rate Limits and Bot Policy

- Rate limit: 60 requests/minute per client IP.
- LLM and search crawler user-agents are recognized and given full read access.