> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gabin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Conventions

> Response envelope, cursor pagination, totals, identifiers, formats and GeoJSON in the Gabin API.

## Response envelope

A successful response is always an object with `data` and `meta`:

```json theme={null}
{
  "data": { "siren": "552081317", "name": "ELECTRICITE DE FRANCE", "…": "…" },
  "meta": {}
}
```

`data` is an object for a single resource and an array for a list. Errors use another shape, described in [errors](https://docs.gabin.ai/errors.md).

## Pagination

Lists are paginated by an opaque cursor.

```json theme={null}
{
  "data": [ … ],
  "meta": {
    "page": { "next_cursor": "eyJ2IjoxLCJvIjozLCJsIjozLCJmIjoiZmNhODgwY2EifQ.myk0rHtG…", "limit": 3 },
    "total": 4643,
    "total_kind": "exact"
  }
}
```

* `limit`: page size, 1 to 100, default 20 (a few endpoints have a lower maximum, stated in the reference).
* `next_cursor`: pass it as `cursor` to get the next page, with the same filters. The page size stays the one of the first page. `null` on the last page.
* A cursor is signed and bound to its endpoint: an altered cursor, or one reused on another endpoint, returns `400 INVALID`.
* At most 10,000 results are reachable for one query (`400 PAGINATION_LIMIT` beyond). Narrow the query with filters or a smaller zone.

```bash theme={null}
curl "https://api.gabin.ai/v1/companies?q=boulangerie&limit=100&cursor=eyJ2Ijox…" \
  -H "Authorization: Bearer $GABIN_API_KEY"
```

### Totals

`meta.total` comes with `meta.total_kind`:

| `total_kind` | Meaning |
| - | - |
| `exact` | The exact number of results |
| `lower_bound` | At least this many; counting stopped there |
| `estimate` | An estimate from the database planner, for very large zones |

## Identifiers

| Identifier | What it is | Example |
| - | - | - |
| SIREN | 9-digit identifier of a legal unit (company, association, sole proprietorship) | `552081317` |
| SIRET | 14 digits: SIREN + 5 digits identifying one establishment | `55208131700011` |
| NAF code | Activity code of the French nomenclature (NAF rév. 2) | `43.29A` |
| INSEE code | 5-character code of a city (municipality); Paris, Lyon and Marseille districts have their own | `69266`, `69382` |
| IRIS code | 9-character code of an Insee statistical district, used as "district" | `692660101` |
| Building id | BDNB building group identifier | `bdnb-bg-1M1D-U5N1-HH7E` |
| Parcel id | Cadastral parcel identifier | `69382000AB0105` |
| Officer id | SIREN of one mandate + 8 hexadecimal characters, stable for the same person | `5821109871464e0b9` |

Identifiers are case-sensitive where shown in mixed case (building ids).

## Formats

* **Field names** are in English, `snake_case`. Labels that come from French registers (activity labels, roles) stay in French.
* **Dates** are ISO 8601: `2014-03-12`, or `YYYY-MM` when the source gives no day (officers' birth month).
* **Amounts** are numbers in euros. **Areas** are in square metres, **lengths** in metres.
* **Coordinates** are WGS84, ordered `[longitude, latitude]` as in GeoJSON.
* **Unknown values** are `null`: a field listed in the reference is present in the response, with `null` when the source has no value.

## GeoJSON

Geographic lists accept `format=geojson` and return a GeoJSON `FeatureCollection` in `data`; each feature carries the same properties as the JSON item. Buildings default to a point (`Point`); add `geometry=footprint` for the outline. Boundaries of zones and parcels are GeoJSON geometries. See the [buildings guide](https://docs.gabin.ai/guides/buildings.md).

## Links to gabin.ai

Most objects include `gabin_url`, the public page of the object on gabin.ai. Use it to show your users the source, or to check a value by eye.

## Versioning

The API is versioned in the path (`/v1`). Within `v1`, a field never changes meaning; new fields and endpoints can be added. Ignore fields you do not know.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.