Skip to main content

​
Response envelope

A successful response is always an object with data and meta:
data is an object for a single resource and an array for a list. Errors use another shape, described in errors.

​
Pagination

Lists are paginated by an opaque cursor.
  • 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.

​
Totals

meta.total comes with meta.total_kind:

​
Identifiers

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.

​
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.