> ## 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 building permits in an area > Building permits (Sitadel) of one area, ordered by permit number: a bounding box (`bbox`, at most 4 km²), a circle (`lat`, `lon`, `radius` up to 1,000 m), a city or arrondissement (`insee`) or a department (`department`). Filters: `status`, `type`, `filed_after` / `filed_before` (default: the last 5 years of filing), `started_after`. Construction sites in progress: `status=started`. Each permit has the fields of GET /v1/buildings/{id}/permits plus `location` (a point in its cadastral parcel, WGS84) and the building on that parcel; only permits matched to a parcel are listed. The applicant is given when it is a legal entity, never an individual. `format=geojson` returns a GeoJSON FeatureCollection of points in `data`, ready for a map source; pagination stays in `meta`. The total is counted on the first page (up to 10,000) and carried by the cursor. Weight: 2 per page. For a map at zoom 15-16, GET /v1/tiles/permits/{z}/{x}/{y}.pbf is lighter. ## OpenAPI ````yaml https://api.gabin.ai/v1/openapi.json get /v1/permits 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/permits: get: tags: - Permits summary: List building permits in an area description: >- Building permits (Sitadel) of one area, ordered by permit number: a bounding box (`bbox`, at most 4 km²), a circle (`lat`, `lon`, `radius` up to 1,000 m), a city or arrondissement (`insee`) or a department (`department`). Filters: `status`, `type`, `filed_after` / `filed_before` (default: the last 5 years of filing), `started_after`. Construction sites in progress: `status=started`. Each permit has the fields of GET /v1/buildings/{id}/permits plus `location` (a point in its cadastral parcel, WGS84) and the building on that parcel; only permits matched to a parcel are listed. The applicant is given when it is a legal entity, never an individual. `format=geojson` returns a GeoJSON FeatureCollection of points in `data`, ready for a map source; pagination stays in `meta`. The total is counted on the first page (up to 10,000) and carried by the cursor. Weight: 2 per page. For a map at zoom 15-16, GET /v1/tiles/permits/{z}/{x}/{y}.pbf is lighter. operationId: listPermits 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: 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 search (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 search (WGS84), with `lat` and `radius`. schema: type: number minimum: -180 maximum: 180 - name: radius in: query required: false description: 'Radius of the circle search, in meters, 1 to 1,000. Example: 300.' schema: type: number minimum: 1 maximum: 1000 - name: insee in: query required: false description: 'INSEE code of a city or arrondissement. Example: "69266".' schema: type: string pattern: ^(\d{5}|2[AaBb]\d{3})$ - name: department in: query required: false description: 'Department code. Example: "69".' schema: type: string pattern: ^(\d{2}|2[AaBb]|97\d)$ - name: status in: query required: false description: >- Statuses, comma-separated: `authorized` (« Autorisé »), `started` (« Commencé »: the works-start declaration was filed; these are the construction sites in progress), `completed` (« Terminé »: the completion declaration was filed). Completion is often never declared, so an old `started` permit may be finished. Example: "started". schema: type: string maxLength: 40 - name: type in: query required: false description: >- Permit types, comma-separated (any of them): `housing` (creates dwellings), `premises` (creates non-residential floor area), `demolition`, `development` (permis d'aménager). Example: "housing". schema: type: string maxLength: 60 - name: filed_after in: query required: false description: >- Filed in or after this year. Default: 5 years before the current year. Example: 2022. schema: type: integer minimum: 1990 maximum: 2100 - name: filed_before in: query required: false description: >- Filed in or before this year. Default: the current year. Example: 2025. schema: type: integer minimum: 1990 maximum: 2100 - name: started_after in: query required: false description: >- Works started on or after this date (YYYY-MM-DD). Example: "2025-01-01". schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ - 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/LocatedPermit' - type: object properties: type: type: string const: FeatureCollection features: type: array items: type: object properties: type: type: string const: Feature id: type: string description: Same as `properties.number`. 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/LocatedPermit' required: - type - id - geometry - properties required: - type - features description: >- Permits as a GeoJSON FeatureCollection of points; `properties` is a permit. description: >- A list of permits, or a FeatureCollection with `format=geojson`. meta: $ref: '#/components/schemas/PageMeta' example: data: - number: PC0692662400031 parcel_id: 69266000AB0012 types: - housing status: Commencé filed_year: 2024 authorized_on: '2024-07-09' works_started_on: '2025-03-03' completed_on: null project_nature: Nouvelle construction main_use: Logements housing_type: Collectif residence_type: Résidence principale annex_type: null housing_created: 38 housing_demolished: 0 living_area_created_m2: 2450 premises_area_created_m2: null land_area_m2: 1830 applicant: siren: '999100074' name: Foncière Gratte-Ciel naf_code: 43.29A naf_label: Travaux d'isolation sector: renovation-energetique created_on: '2014-03-12' active: true partial_diffusion: false gabin_url: >- https://gabin.ai/entreprise/atelier-thermique-du-rhone-999100017 legal_form: SAS, société par actions simplifiée headcount_range: '11' headquarters: address: 12 rue Émile Zola postal_code: '69100' city: Villeurbanne siret: '99910001700011' insee: '69266' location: - 4.8795 - 45.7665 building_id: bdnb-bg-CJ69-HW8G-PTTG latest_revenue: null latest_revenue_year_end: null location: - 4.8801 - 45.7671 building_id: bdnb-bg-CJ69-HW8G-PTTG gabin_url: https://gabin.ai/batiment/bdnb-bg-CJ69-HW8G-PTTG meta: page: next_cursor: null limit: 20 total: 1 total_kind: exact '400': description: INVALID, PAGINATION_LIMIT headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: 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: LocatedPermit: type: object properties: number: type: string description: Permit number. parcel_id: type: string description: Cadastral parcel of the permit. types: type: array items: type: string enum: - housing - premises - demolition - development description: >- `housing` creation, `premises` (non-residential), `demolition`, `development`. status: description: Status, in French (autorisé, commencé, terminé…). type: - string - 'null' filed_year: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: Year the application was filed. authorized_on: description: Authorization date (YYYY-MM-DD). type: - string - 'null' works_started_on: description: Works start date (YYYY-MM-DD). type: - string - 'null' completed_on: description: Completion date (YYYY-MM-DD). type: - string - 'null' project_nature: description: Nature of the project, in French. type: - string - 'null' main_use: description: Main use of the project, in French. type: - string - 'null' housing_type: description: Type of dwellings created, in French. type: - string - 'null' residence_type: description: Main or secondary residence, in French. type: - string - 'null' annex_type: description: Type of annex, in French. type: - string - 'null' housing_created: description: Dwellings created. type: - number - 'null' housing_demolished: description: Dwellings demolished. type: - number - 'null' living_area_created_m2: description: Living area created, in m². type: - number - 'null' premises_area_created_m2: description: Non-residential area created, in m². type: - number - 'null' land_area_m2: description: Land area, in m². type: - number - 'null' applicant: anyOf: - $ref: '#/components/schemas/CompanySummary' - type: 'null' description: >- Applicant (maître d'ouvrage) when it is a legal entity; never an individual. location: type: array prefixItems: - type: number - type: number items: false minItems: 2 maxItems: 2 description: A point inside the permit's cadastral parcel, WGS84 `[lon, lat]`. building_id: anyOf: - type: string maxLength: 40 pattern: ^bdnb-[a-z]{2,4}-[A-Za-z0-9]{4}(-[A-Za-z0-9]{4})*$ description: >- BDNB building id (`batiment_groupe_id`). Example: "bdnb-bg-CJ69-HW8G-PTTG". - type: 'null' description: >- BDNB building on that parcel (the closest to the point); null for bare land. Details: GET /v1/buildings/{id}. gabin_url: description: Page of that building on the gabin.ai map; null without a building. type: - string - 'null' required: - number - parcel_id - types - status - filed_year - authorized_on - works_started_on - completed_on - project_nature - main_use - housing_type - residence_type - annex_type - housing_created - housing_demolished - living_area_created_m2 - premises_area_created_m2 - land_area_m2 - applicant - location - building_id - gabin_url description: A building permit (Sitadel) with its position. 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`. CompanySummary: type: object properties: siren: type: string description: 'SIREN: 9 digits. Example: 552100554.' name: type: string description: >- Registered name; first and last name for a sole proprietorship. Neutral label under partial diffusion ("Entrepreneur individuel"). Example: "Atelier Thermique du Rhône". naf_code: type: string description: 'NAF rev. 2 sub-class of the company. Example: "43.29A".' naf_label: type: string description: 'Label of the NAF code, in French. Example: "Travaux d''isolation".' sector: description: Gabin sector slug of the NAF code, null outside sectors. type: - string - 'null' created_on: description: Creation date (YYYY-MM-DD). type: - string - 'null' active: type: boolean description: False when the company has ceased (SIRENE state C). partial_diffusion: type: boolean description: >- True when the company is under SIRENE partial diffusion: no name of the person, address limited to the city, no position, no building, no officers. gabin_url: type: string description: Page of the company on gabin.ai. legal_form: description: >- Legal form, in French: the usual short name when there is one ("SAS", "SARL", "SCI", "Entrepreneur individuel"), otherwise the INSEE label of the legal category ("Société de participations financières de profession libérale (SARL)"). INSEE category code: GET /v1/companies/{siren}. Example: "SAS". type: - string - 'null' headcount_range: type: string enum: - '11' - '12' - '21' - '22' - '31' - '32' - '41' - '42' - '51' - '52' - '53' - NN - '00' - '01' - '02' - '03' description: >- INSEE headcount range code. "NN": not reported. See GET /v1/headcount-ranges. headquarters: type: object properties: address: type: string description: Street of the registered office; empty under partial diffusion. postal_code: description: 'Postal code. Example: "69100".' type: - string - 'null' city: type: string description: 'City. Example: "Villeurbanne".' siret: description: >- SIRET of the registered office; null when SIRENE knows none. Present in GET /v1/companies and in an officer's mandates (GET /v1/officers/{id}); absent from other lists. Example: "55210055400013". type: - string - 'null' insee: description: >- INSEE code of the city of the registered office. Present in GET /v1/companies and in an officer's mandates (GET /v1/officers/{id}); absent from other lists. Example: "69266". type: - string - 'null' location: description: >- Geocoded position `[lon, lat]` (WGS84) of the registered office at street-number or street level, as in GET /v1/companies/{siren}/establishments; null when only the city is known or under partial diffusion. Present in GET /v1/companies and in an officer's mandates (GET /v1/officers/{id}); absent from other lists. 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' building_id: description: >- BDNB building id (batiment_groupe_id) the registered office occupies, when its address matches a building at street-number level; null otherwise or under partial diffusion. Present in GET /v1/companies and in an officer's mandates (GET /v1/officers/{id}); absent from other lists. Example: "bdnb-bg-CJ69-HW8G-PTTG". type: - string - 'null' required: - address - postal_code - city latest_revenue: description: >- Latest reported revenue, present only when results are ranked by revenue (no `q`, `insee`, `iris` or `department`). Otherwise see GET /v1/companies/{siren}/financials. In euros; null when not reported. type: - number - 'null' latest_revenue_year_end: description: Fiscal year end (YYYY-MM-DD) of `latest_revenue`. type: - string - 'null' required: - siren - name - naf_code - naf_label - sector - created_on - active - partial_diffusion - gabin_url - legal_form - headcount_range - headquarters - latest_revenue - latest_revenue_year_end description: A company in a list. 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.