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

# Get the market summary around a building

> Market summary of the building's city and district: median sale price per m² and its change (DVF), rents (ANIL), population (INSEE), income (FiLoSoFi). Full series: GET /v1/zones/{level}/{code}/market.



## OpenAPI

````yaml https://api.gabin.ai/v1/openapi.json get /v1/buildings/{id}/market
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 <key>`: 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/buildings/{id}/market:
    get:
      tags:
        - Buildings
      summary: Get the market summary around a building
      description: >-
        Market summary of the building's city and district: median sale price
        per m² and its change (DVF), rents (ANIL), population (INSEE), income
        (FiLoSoFi). Full series: GET /v1/zones/{level}/{code}/market.
      operationId: getBuildingMarket
      parameters:
        - name: id
          in: path
          required: true
          description: >-
            BDNB building id (`batiment_groupe_id`). Example:
            "bdnb-bg-CJ69-HW8G-PTTG".
          schema:
            type: string
            maxLength: 40
            pattern: ^bdnb-[a-z]{2,4}-[A-Za-z0-9]{4}(-[A-Za-z0-9]{4})*$
      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:
                    $ref: '#/components/schemas/BuildingMarket'
                  meta:
                    type: object
                    description: Empty for a single resource.
        '400':
          description: INVALID
          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
        '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
        '404':
          description: NOT_FOUND
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                NOT_FOUND:
                  value:
                    error:
                      code: NOT_FOUND
                      message: No company with SIREN 999999999.
                      docs_url: https://docs.gabin.ai/errors#not_found
        '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:
    BuildingMarket:
      type: object
      properties:
        city:
          description: City name.
          type:
            - string
            - 'null'
        district:
          description: District name.
          type:
            - string
            - 'null'
        price:
          anyOf:
            - type: object
              properties:
                year:
                  type: integer
                  minimum: -9007199254740991
                  maximum: 9007199254740991
                  description: Year of the figures.
                city_median_m2:
                  description: >-
                    Median price per m² in the city. In euros; null when not
                    reported.
                  type:
                    - number
                    - 'null'
                district_median_m2:
                  description: >-
                    Median price per m² in the district. In euros; null when not
                    reported.
                  type:
                    - number
                    - 'null'
                change_pct:
                  description: Yearly change of the city median, in percent.
                  type:
                    - number
                    - 'null'
              required:
                - year
                - city_median_m2
                - district_median_m2
                - change_pct
            - type: 'null'
          description: Sale prices (DVF).
        rent:
          anyOf:
            - type: object
              properties:
                year:
                  type: integer
                  minimum: -9007199254740991
                  maximum: 9007199254740991
                  description: Year.
                apartment_m2:
                  type: number
                  description: Apartment rent, in euros per m² per month.
              required:
                - year
                - apartment_m2
            - type: 'null'
          description: Rents (ANIL).
        population:
          anyOf:
            - type: object
              properties:
                year:
                  type: integer
                  minimum: -9007199254740991
                  maximum: 9007199254740991
                  description: Census year.
                total:
                  type: number
                  description: Population.
                managers_pct:
                  description: >-
                    Share of managers and higher intellectual professions, in
                    percent.
                  type:
                    - number
                    - 'null'
              required:
                - year
                - total
                - managers_pct
            - type: 'null'
          description: Population (INSEE census).
        income:
          anyOf:
            - type: object
              properties:
                year:
                  type: integer
                  minimum: -9007199254740991
                  maximum: 9007199254740991
                  description: Year.
                median_disposable:
                  type: number
                  description: >-
                    Median disposable income per consumption unit, in euros per
                    year.
                poverty_rate_pct:
                  description: Poverty rate, in percent.
                  type:
                    - number
                    - 'null'
                level:
                  type: string
                  enum:
                    - district
                    - city
                  description: Level the figures come from.
              required:
                - year
                - median_disposable
                - poverty_rate_pct
                - level
            - type: 'null'
          description: Income (INSEE FiLoSoFi).
      required:
        - city
        - district
        - price
        - rent
        - population
        - income
      description: >-
        Market summary around the building. Full series: GET
        /v1/zones/{level}/{code}/market.
    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.