> ## 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. # List establishments in an area > Establishments (SIRET) in one area, ordered by SIRET: a city or arrondissement (`insee`; 75056, 69123, 13055 cover all arrondissements), a department (`department`), a district (`iris`), a bounding box (`bbox`, at most 4 km²) or a circle (`lat`, `lon`, `radius` up to 1,000 m). Filters: `naf` (activity of the establishment), `headcount`, `headquarters_only`, `include_closed` (default: open establishments only). Each item is an establishment with its address, INSEE code, NAF code, `location` (`[lon, lat]`, street level at least; null when only the city is known), `building_id`, and the name and legal form of its company. Positions are included: never geocode an establishment address. `bbox`, `iris` and circles list only establishments positioned at street level, never ones under partial diffusion. `format=geojson` returns a GeoJSON FeatureCollection of points in `data`, ready for a map source, and lists only positioned establishments (in every area type; the total counts them only). The total is counted on the first page (up to 10,000) and carried by the cursor. A department or a large city with a rare filter can take too long (`TIMEOUT`): add `headquarters_only=true` with `naf`, or narrow the area. Weight: 2 per page. ## OpenAPI ````yaml https://api.gabin.ai/v1/openapi.json get /v1/establishments openapi: 3.1.0 info: title: Gabin API version: 1.0.0 description: >- French company and real-estate data for builders: companies (SIRENE, RNE), establishments, officers, annual accounts, buildings (BDNB), parcels, addresses, zones, multi-criteria search, vector tiles, reference data. Guides: https://docs.gabin.ai. **Authentication.** Every endpoint except `/v1/health` and `/v1/openapi.json` requires `Authorization: Bearer `: an API key (`gab_live_…`, created at https://gabin.ai/compte/api) or an OAuth access token (`gat_…`, MCP connectors). **Limits (free plan).** 600 weighted requests per minute and 20,000 units per UTC day per account. A request weighs 1 unless its endpoint states otherwise. Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-Quota-Remaining` and `X-Request-Id`. **Responses.** Success: `{ "data": …, "meta": { … } }`. Lists are paginated by an opaque cursor (`meta.page.next_cursor`, up to 100 per page and 10,000 results per query). Errors: `{ "error": { "code", "message", "docs_url" } }`. Dates are ISO 8601, amounts in euros, areas in m², coordinates WGS84 `[lon, lat]`. **Data rules.** Companies under SIRENE partial diffusion are returned without the person's name, street address, position or building. Officers come from public registers only (name, first names, month and year of birth, mandates), without contact details. No contact data is exposed. contact: name: Gabin url: https://gabin.ai servers: - url: https://api.gabin.ai security: - bearerAuth: [] tags: - name: Companies description: >- Companies (SIRENE legal units): search with filters, profile, establishments, officers, annual accounts. - name: Establishments description: 'Establishments (SIRENE): by SIRET, or listed in an area.' - name: Officers description: >- Company officers from public registers (RNE): search by name, mandates, relationships. - name: Reference data description: >- Values accepted by the filters: NAF activities, legal form families, headcount ranges. - name: Account description: 'The account behind the API key: plan, limits, remaining quota.' - name: Meta description: Service status and OpenAPI document. No authentication. - name: Buildings description: >- French buildings (BDNB): profile, linked companies, sections (energy, transactions, owners, condominium, parcels, parking, permits, fiber, planning, market) and geographic search. - name: Permits description: >- Building permits (Sitadel) of an area with their position: construction sites in progress, authorized and completed projects. - name: Parcels description: 'Cadastral parcels: boundary, area, buildings.' - name: Addresses description: >- Address geocoding (Base Adresse Nationale) with the BDNB building at the address, and named places. - name: Zones description: >- Cities, districts (merged IRIS), departments, and market figures of a zone (prices, rents, demography, income). - name: Search description: >- Multi-criteria search on buildings or companies in a zone: a catalog of fields, AND conditions, OR groups. - name: Tiles description: Vector tiles (Mapbox Vector Tile) of the gabin.ai map layers. paths: /v1/establishments: get: tags: - Establishments summary: List establishments in an area description: >- Establishments (SIRET) in one area, ordered by SIRET: a city or arrondissement (`insee`; 75056, 69123, 13055 cover all arrondissements), a department (`department`), a district (`iris`), a bounding box (`bbox`, at most 4 km²) or a circle (`lat`, `lon`, `radius` up to 1,000 m). Filters: `naf` (activity of the establishment), `headcount`, `headquarters_only`, `include_closed` (default: open establishments only). Each item is an establishment with its address, INSEE code, NAF code, `location` (`[lon, lat]`, street level at least; null when only the city is known), `building_id`, and the name and legal form of its company. Positions are included: never geocode an establishment address. `bbox`, `iris` and circles list only establishments positioned at street level, never ones under partial diffusion. `format=geojson` returns a GeoJSON FeatureCollection of points in `data`, ready for a map source, and lists only positioned establishments (in every area type; the total counts them only). The total is counted on the first page (up to 10,000) and carried by the cursor. A department or a large city with a rare filter can take too long (`TIMEOUT`): add `headquarters_only=true` with `naf`, or narrow the area. Weight: 2 per page. operationId: listEstablishments parameters: - name: cursor in: query required: false description: >- Cursor returned in `meta.page.next_cursor` by the previous page. Keep the same filters; the page size is the one of the first page. schema: type: string maxLength: 300 - name: limit in: query required: false description: Results per page, 1 to 100. Default 20. schema: default: 20 type: integer minimum: 1 maximum: 100 - name: insee in: query required: false description: >- INSEE code of a city or of a Paris, Lyon or Marseille arrondissement; the city code of Paris (75056), Lyon (69123) or Marseille (13055) covers all its arrondissements. Example: "69266". schema: type: string pattern: ^(\d{5}|2[AaBb]\d{3})$ - name: department in: query required: false description: 'Department code. Example: "69", "2A", "974".' schema: type: string pattern: ^(\d{2,3}|2[AaBb])$ - name: iris in: query required: false description: 'IRIS code of a district (9 characters). Example: "692660101".' schema: type: string pattern: ^(\d{5}|2[AaBb]\d{3})\d{4}$ - name: bbox in: query required: false description: >- Bounding box "minLon,minLat,maxLon,maxLat" (WGS84), at most 4 km² (2 km × 2 km). Example: "4.876,45.765,4.886,45.771". schema: type: string maxLength: 120 - name: lat in: query required: false description: Latitude of the center of a circle (WGS84), with `lon` and `radius`. schema: type: number minimum: -90 maximum: 90 - name: lon in: query required: false description: >- Longitude of the center of a circle (WGS84), with `lat` and `radius`. schema: type: number minimum: -180 maximum: 180 - name: radius in: query required: false description: 'Radius of the circle, in meters, 1 to 1,000. Example: 300.' schema: type: number minimum: 1 maximum: 1000 - name: naf in: query required: false description: >- Activities of the establishment, comma-separated, up to 20: NAF rev. 2 sub-classes ("43.29A"), divisions ("47") or sections ("G"). See GET /v1/naf. Example: "43.22A,43.22B". schema: type: string maxLength: 200 - name: headcount in: query required: false description: >- INSEE headcount range code of the establishment. See GET /v1/headcount-ranges. Example: "11" (10 to 19 employees). schema: type: string enum: - '11' - '12' - '21' - '22' - '31' - '32' - '41' - '42' - '51' - '52' - '53' - NN - '00' - '01' - '02' - '03' - name: headquarters_only in: query required: false description: Registered offices only. Default false. schema: type: string enum: - '0' - '1' - 'true' - 'false' - name: include_closed in: query required: false description: >- Include closed establishments. Default false: open establishments only. schema: type: string enum: - '0' - '1' - 'true' - 'false' - name: format in: query required: false description: >- `json` (default): a list of objects in `data`. `geojson`: `data` is a GeoJSON FeatureCollection (same pagination in `meta`). schema: default: json type: string enum: - json - geojson responses: '200': description: OK headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Quota-Remaining: $ref: '#/components/headers/X-Quota-Remaining' content: application/json: schema: type: object required: - data - meta properties: data: anyOf: - type: array items: $ref: '#/components/schemas/EstablishmentInArea' - type: object properties: type: type: string const: FeatureCollection features: type: array items: type: object properties: type: type: string const: Feature id: type: string description: SIRET, same as `properties.siret`. geometry: anyOf: - type: object properties: type: type: string const: Point coordinates: type: array prefixItems: - type: number - type: number items: false minItems: 2 maxItems: 2 description: >- WGS84 coordinates `[lon, lat]`. Example: [4.8795, 45.7665]. required: - type - coordinates description: GeoJSON Point, WGS84. - type: object properties: type: type: string enum: - Polygon - MultiPolygon coordinates: type: array items: {} description: >- GeoJSON coordinates: rings of `[lon, lat]` positions (WGS84). required: - type - coordinates description: GeoJSON Polygon or MultiPolygon, WGS84. description: >- GeoJSON geometry (Point, Polygon or MultiPolygon), WGS84. properties: $ref: '#/components/schemas/EstablishmentInArea' required: - type - id - geometry - properties required: - type - features description: >- Establishments as a GeoJSON FeatureCollection of points (`location`); `properties` is the establishment. description: >- A list of establishments, or a FeatureCollection with `format=geojson`. meta: $ref: '#/components/schemas/PageMeta' example: data: - siret: '99910001700011' siren: '999100017' headquarters: true trade_name: null address: 12 rue Émile Zola postal_code: '69100' city: Villeurbanne insee: '69266' naf_code: 43.29A created_on: '2014-03-12' closed_on: null active: true building_id: bdnb-bg-CJ69-HW8G-PTTG location: - 4.8795 - 45.7665 company_name: Atelier Thermique du Rhône legal_form: SAS meta: page: next_cursor: null limit: 20 total: 1 total_kind: exact '400': description: ZONE_REQUIRED, INVALID, PAGINATION_LIMIT headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: ZONE_REQUIRED: value: error: code: ZONE_REQUIRED message: Add a location (insee, iris, department) or a name (q). docs_url: https://docs.gabin.ai/errors#zone_required INVALID: value: error: code: INVALID message: 'limit: Too big: expected number to be <=100' docs_url: https://docs.gabin.ai/errors#invalid PAGINATION_LIMIT: value: error: code: PAGINATION_LIMIT message: >- At most 10,000 results can be reached for one query. Narrow the filters. docs_url: https://docs.gabin.ai/errors#pagination_limit '401': description: UNAUTHENTICATED headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: UNAUTHENTICATED: value: error: code: UNAUTHENTICATED message: Invalid or revoked API key. docs_url: https://docs.gabin.ai/errors#unauthenticated '429': description: RATE_LIMITED, QUOTA_EXCEEDED headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: value: error: code: RATE_LIMITED message: >- Rate limit reached (600 weighted requests per minute). Retry in 12 s. docs_url: https://docs.gabin.ai/errors#rate_limited QUOTA_EXCEEDED: value: error: code: QUOTA_EXCEEDED message: >- Daily quota reached (20000 units per UTC day). It resets at 00:00 UTC. docs_url: https://docs.gabin.ai/errors#quota_exceeded '503': description: TIMEOUT, BUSY headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/Error' examples: TIMEOUT: value: error: code: TIMEOUT message: The query took too long. Narrow it down and retry. docs_url: https://docs.gabin.ai/errors#timeout BUSY: value: error: code: BUSY message: >- The API is serving too many database requests right now. Retry in 1 s. docs_url: https://docs.gabin.ai/errors#busy components: headers: X-Request-Id: description: Unique id of the request; quote it when contacting support. schema: type: string X-RateLimit-Limit: description: Weighted requests allowed per minute for the account. schema: type: integer X-RateLimit-Remaining: description: Weighted requests left in the current minute. schema: type: integer X-RateLimit-Reset: description: Seconds until the per-minute window resets. schema: type: integer X-Quota-Remaining: description: Units left in the daily quota (UTC day). schema: type: integer Retry-After: description: Seconds to wait before retrying. schema: type: integer schemas: EstablishmentInArea: type: object properties: siret: type: string description: 'SIRET: 14 digits. Example: 55210055400013.' siren: type: string description: SIREN of the company that owns the establishment. headquarters: type: boolean description: True for the registered office (siège). trade_name: description: 'Sign or trade name (enseigne) when declared. Example: "Le Comptoir".' type: - string - 'null' address: type: string description: >- Street address. Limited to "postal code + city" when the establishment is under SIRENE partial diffusion or has no street. Example: "12 rue Émile Zola". postal_code: description: 'Postal code. Example: "69100".' type: - string - 'null' city: description: 'City name. Example: "Villeurbanne".' type: - string - 'null' insee: description: >- INSEE code of the city (5 characters); null outside France. Example: "69266". type: - string - 'null' naf_code: description: >- NAF rev. 2 code of the establishment, may differ from the company's. Example: "43.29A". type: - string - 'null' created_on: description: Creation date (YYYY-MM-DD). type: - string - 'null' closed_on: description: >- Closing date (YYYY-MM-DD) when the establishment is closed, else null. type: - string - 'null' active: type: boolean description: True when the establishment is open (SIRENE state A). building_id: description: >- BDNB building id (batiment_groupe_id) the establishment occupies, when its address matches a building at street-number level. Example: "bdnb-bg-CJ69-HW8G-PTTG". type: - string - 'null' location: anyOf: - type: array prefixItems: - type: number - type: number items: false minItems: 2 maxItems: 2 description: 'WGS84 coordinates `[lon, lat]`. Example: [4.8795, 45.7665].' - type: 'null' description: >- Geocoded position `[lon, lat]` (WGS84) at street-number or street level; null when only the city is known. company_name: type: string description: >- Name of the company (neutral label when the company is under partial diffusion). legal_form: description: >- Legal form of the company, in French: the usual short name when there is one ("SAS", "SARL", "SCI", "Entrepreneur individuel"), otherwise the INSEE label of the category. Example: "SAS". type: - string - 'null' required: - siret - siren - headquarters - trade_name - address - postal_code - city - insee - naf_code - created_on - closed_on - active - building_id - location - company_name - legal_form description: >- An establishment in an area, with the name and legal form of its company. PageMeta: type: object properties: page: type: object properties: next_cursor: description: >- Opaque cursor for the next page: pass it as `cursor` with the same filters. Null on the last page or once 10,000 results have been reached. type: - string - 'null' limit: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Page size used for this response. required: - next_cursor - limit total: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Number of matching results, qualified by `total_kind`. Example: 8337. total_kind: type: string enum: - exact - lower_bound - estimate description: >- `exact`: counted. `lower_bound`: at least this many (counting stopped). `estimate`: database planner estimate, can be off by a few percent. required: - page - total - total_kind description: Pagination metadata of a list response. Error: type: object properties: error: type: object properties: code: type: string enum: - UNAUTHENTICATED - FORBIDDEN - NOT_FOUND - INVALID - ZONE_REQUIRED - PAGINATION_LIMIT - RATE_LIMITED - QUOTA_EXCEEDED - TIMEOUT - BUSY - INTERNAL description: Stable machine-readable code. message: type: string description: Human-readable explanation, in English. docs_url: type: string description: Documentation page for this error code. required: - code - message - docs_url required: - error description: Error body. The HTTP status matches `error.code`. securitySchemes: bearerAuth: type: http scheme: bearer description: API key `gab_live_…` or OAuth access token `gat_…`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.