> ## 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. # Geocode an address > Geocodes a French address with the Base Adresse Nationale (public service) and returns the normalized address, its point, and, for a house-number match, the BDNB building at that point (inside it, or within 30 m). Next: GET /v1/buildings/{id}. ## OpenAPI ````yaml https://api.gabin.ai/v1/openapi.json get /v1/geocode 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/geocode: get: tags: - Addresses summary: Geocode an address description: >- Geocodes a French address with the Base Adresse Nationale (public service) and returns the normalized address, its point, and, for a house-number match, the BDNB building at that point (inside it, or within 30 m). Next: GET /v1/buildings/{id}. operationId: geocodeAddress parameters: - name: q in: query required: true description: >- Address to geocode, free text. Example: "40 rue de Bruxelles Villeurbanne". schema: type: string minLength: 3 maxLength: 200 - name: limit in: query required: false description: Results, 1 to 10. Default 5. schema: default: 5 type: integer minimum: 1 maximum: 10 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/GeocodeResult' meta: $ref: '#/components/schemas/PageMeta' '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 (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: 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: GeocodeResult: type: object properties: label: type: string description: >- Normalized address. Example: "40 Rue de Bruxelles 69100 Villeurbanne". name: type: string description: >- Number and street, street, or place name. Example: "40 Rue de Bruxelles". postal_code: description: Postal code. type: - string - 'null' city: description: City. type: - string - 'null' insee: description: INSEE code of the city. type: - string - 'null' precision: type: string enum: - housenumber - street - locality - municipality description: 'Level matched: a house number, a street, a locality, a whole city.' score: type: number description: Match score of the BAN, 0 to 1. location: type: array prefixItems: - type: number - type: number items: false minItems: 2 maxItems: 2 description: 'WGS84 coordinates `[lon, lat]`. Example: [4.8795, 45.7665].' building: anyOf: - type: object properties: id: 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". address: type: string description: Street address (or the id when the building has no address). name: description: Name of the place, when known. type: - string - 'null' gabin_url: type: string description: Page of the building on the gabin.ai map. required: - id - address - name - gabin_url - type: 'null' description: >- BDNB building at the address point, only for a `housenumber` match. Next: GET /v1/buildings/{id}. required: - label - name - postal_code - city - insee - precision - score - location - building description: A geocoded address (Base Adresse Nationale). 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.