> ## 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. # Run a multi-criteria search > Lists the buildings or companies (registered offices) matching a search, in a stable order, paginated by cursor (pass `meta.page.next_cursor` as `cursor` with the same filters). `meta.total` is a lower bound while pages remain: POST /v1/search/count gives the total. A search has a `target` (`buildings` or `companies`), a `zone` (city, district, postal code; department for buildings only), `conditions` that all apply (AND) and optional `any_of` groups (at least one condition of each group applies). Each condition names a field from GET /v1/search/fields and gives `values`, or `min`/`max`, according to the field's `operator`. Example: {"target": "buildings", "zone": {"type": "city", "code": "69266"}, "conditions": [{"field": "batiment.annee_construction", "max": 1974}, {"field": "dpe.classe", "values": ["F", "G"]}]} Weight: 5 (counts 5× against the rate limit and the daily quota). ## OpenAPI ````yaml https://api.gabin.ai/v1/openapi.json post /v1/search 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).** 60 weighted requests per minute and 5,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. - 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: 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/search: post: tags: - Search summary: Run a multi-criteria search description: >- Lists the buildings or companies (registered offices) matching a search, in a stable order, paginated by cursor (pass `meta.page.next_cursor` as `cursor` with the same filters). `meta.total` is a lower bound while pages remain: POST /v1/search/count gives the total. A search has a `target` (`buildings` or `companies`), a `zone` (city, district, postal code; department for buildings only), `conditions` that all apply (AND) and optional `any_of` groups (at least one condition of each group applies). Each condition names a field from GET /v1/search/fields and gives `values`, or `min`/`max`, according to the field's `operator`. Example: {"target": "buildings", "zone": {"type": "city", "code": "69266"}, "conditions": [{"field": "batiment.annee_construction", "max": 1974}, {"field": "dpe.classe", "values": ["F", "G"]}]} Weight: 5 (counts 5× against the rate limit and the daily quota). operationId: search parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchRequest' 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: type: array items: $ref: '#/components/schemas/SearchRow' meta: $ref: '#/components/schemas/PageMeta' '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 (60 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 (5000 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: schemas: SearchRequest: type: object properties: target: type: string enum: - buildings - companies description: >- `buildings` returns BDNB buildings; `companies` returns registered offices. zone: description: >- Area searched. Required: without it (whole France), and for companies in a whole department, the search is refused with `ZONE_REQUIRED`. type: object properties: type: type: string enum: - city - district - postal_code - department description: Zone type. code: type: string maxLength: 12 description: >- INSEE code (city, "69266"), IRIS code (district, "692660101"), postal code ("69100") or department ("69"). Departments are accepted for buildings only. required: - type - code conditions: default: [] description: 'All conditions apply (AND). Empty: everything in the zone.' maxItems: 12 type: array items: type: object properties: field: type: string maxLength: 60 description: Field id from GET /v1/search/fields. values: default: [] description: >- Codes (enum), NAF codes (naf), ["true"] or ["false"] (boolean), [prefix] (text). maxItems: 40 type: array items: type: string maxLength: 120 min: default: null description: Lower bound, inclusive (number). type: - number - 'null' max: default: null description: Upper bound, inclusive (number). type: - number - 'null' required: - field - values - min - max description: One condition on a catalog field. any_of: default: [] description: >- OR groups: at least one condition of each group applies. Up to 4 groups, 12 conditions in total. maxItems: 4 type: array items: type: object properties: conditions: minItems: 2 maxItems: 6 type: array items: type: object properties: field: type: string maxLength: 60 description: Field id from GET /v1/search/fields. values: default: [] description: >- Codes (enum), NAF codes (naf), ["true"] or ["false"] (boolean), [prefix] (text). maxItems: 40 type: array items: type: string maxLength: 120 min: default: null description: Lower bound, inclusive (number). type: - number - 'null' max: default: null description: Upper bound, inclusive (number). type: - number - 'null' required: - field - values - min - max description: One condition on a catalog field. required: - conditions cursor: description: '`meta.page.next_cursor` of the previous page, with the same filters.' type: string maxLength: 400 limit: default: 20 description: Results per page, 1 to 100. Default 20. type: integer minimum: 1 maximum: 100 required: - target - conditions - any_of - limit SearchRow: oneOf: - type: object properties: type: type: string const: building id: type: string description: 'BDNB building id. Next: GET /v1/buildings/{id}.' address: type: string description: Main address. city: description: City. type: - string - 'null' usage: description: Main use (BDNB label, in French). type: - string - 'null' construction_year: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: Construction year. housing_units: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: Dwellings. dpe_class: anyOf: - type: string enum: - A - B - C - D - E - F - G - type: 'null' description: Representative energy class. gabin_url: type: string description: Page on gabin.ai. required: - type - id - address - city - usage - construction_year - housing_units - dpe_class - gabin_url - type: object properties: type: type: string const: company siren: type: string description: 'SIREN. Next: GET /v1/companies/{siren}.' name: type: string description: Name. naf_code: description: NAF code. type: - string - 'null' naf_label: type: string description: NAF label, in French. city: description: City of the registered office. 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. headquarters_building_id: description: BDNB building of the registered office, when matched. type: - string - 'null' gabin_url: type: string description: Page on gabin.ai. required: - type - siren - name - naf_code - naf_label - city - headcount_range - headquarters_building_id - gabin_url description: 'A result: a building (`type: building`) or a company (`type: 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`. 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 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.