{"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.\n\n**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).\n\n**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`.\n\n**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]`.\n\n**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/companies":{"get":{"operationId":"listCompanies","summary":"Search companies","description":"Companies matching a name and/or filters (activity, location, size, legal form, revenue, creation date).\n\nWith a location (`insee`, `iris`, `department`), a company matches when it has an establishment there, open or closed (`headquarters_only=true` for the registered office only); results come newest first in a city, in index order in a department. With a name (`q`), exact names come first. With neither, the largest active companies by latest revenue are returned (`latest_revenue` filled); a rare activity can take too long and answers `ZONE_REQUIRED`.\n\nReturns company summaries; call GET /v1/companies/{siren} for a full profile.","tags":["Companies"],"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":"q","in":"query","required":false,"description":"Company name (prefix or contained words), SIREN or SIRET. Example: \"atelier thermique\".","schema":{"type":"string","maxLength":120}},{"name":"naf","in":"query","required":false,"description":"Activities, 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":"sector","in":"query","required":false,"description":"Gabin sector: a named group of NAF sub-classes. Example: plomberie-chauffage.","schema":{"type":"string","enum":["renovation-energetique","plomberie-chauffage","electricite","maconnerie-gros-oeuvre","menuiserie-charpente","second-oeuvre","promotion-immobiliere","immobilier","foncieres","architecture-ingenierie","services-aux-batiments","restauration","hebergement","commerce-alimentaire","commerce-de-detail","automobile","sante","medico-social","enseignement","informatique","telecoms","energie","conseil","juridique-comptable","banque-assurance","transport-logistique","industrie","agriculture","associations-culture-sport","services-personnels"]}},{"name":"insee","in":"query","required":false,"description":"INSEE code of a city or of a Paris, Lyon or Marseille arrondissement. Example: \"69266\".","schema":{"type":"string","pattern":"^(\\d{5}|2[AaBb]\\d{3})$"}},{"name":"iris","in":"query","required":false,"description":"IRIS code of a district (9 characters, starts with its city INSEE code). Implies `insee`. Example: \"692660101\".","schema":{"type":"string","pattern":"^(\\d{5}|2[AaBb]\\d{3})\\d{4}$"}},{"name":"department","in":"query","required":false,"description":"Department code. Example: \"69\", \"2A\", \"974\".","schema":{"type":"string","pattern":"^(\\d{2,3}|2[AaBb])$"}},{"name":"headcount","in":"query","required":false,"description":"INSEE headcount range code of the company. 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":"legal_form","in":"query","required":false,"description":"Legal form families, comma-separated: sas, sarl, sa, sci, scpi, association, public. See GET /v1/legal-forms. Example: \"sas,sarl\".","schema":{"type":"string","maxLength":80}},{"name":"revenue_min","in":"query","required":false,"description":"Minimum latest reported revenue, in euros. Example: 1000000.","schema":{"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"revenue_max","in":"query","required":false,"description":"Maximum latest reported revenue, in euros.","schema":{"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"include_closed","in":"query","required":false,"description":"Include ceased companies. Default false: active companies only.","schema":{"type":"string","enum":["0","1","true","false"]}},{"name":"headquarters_only","in":"query","required":false,"description":"With a location filter: match on the registered office only. Default false: any company with an establishment (open or closed) in the area.","schema":{"type":"string","enum":["0","1","true","false"]}},{"name":"created_after","in":"query","required":false,"description":"Companies created on or after this date (YYYY-MM-DD). Requires `insee`, `iris` or `department`.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"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/CompanySummary"}},"meta":{"$ref":"#/components/schemas/PageMeta"}}},"example":{"data":[{"siren":"999100017","name":"Atelier Thermique du Rhône","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"},"latest_revenue":null,"latest_revenue_year_end":null}],"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 (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"}}}}}}}}}},"/v1/companies/{siren}":{"get":{"operationId":"getCompany","summary":"Get a company","description":"Profile of a company by SIREN: identity, activity, legal form, size, registered office (address, district, building), registry facts (RNE), latest accounts summary and collective procedure (BODACC).\n\nCeased companies are returned with `active: false`. Next: `/establishments`, `/officers` and `/financials` under the same path.","tags":["Companies"],"parameters":[{"name":"siren","in":"path","required":true,"description":"SIREN of the company: 9 digits, no spaces. Example: 552100554.","schema":{"type":"string","pattern":"^\\d{9}$"}}],"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/Company"},"meta":{"type":"object","description":"Empty for a single resource."}}},"example":{"data":{"siren":"999100017","name":"Atelier Thermique du Rhône","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":{"code":"5710","label":"SAS, société par actions simplifiée"},"headcount_range":{"code":"11","label":"10 à 19 salariés"},"headquarters":{"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]},"latest_revenue":null,"latest_revenue_year_end":null,"acronym":null,"sole_proprietorship":false,"naf_section":{"code":"F","label":"Construction"},"category":"PME","social_economy":false,"share_capital":50000,"vat_number":"FR63999100017","city":{"insee":"69266","name":"Villeurbanne","department":"69"},"district":{"iris":"692660101","name":"Gratte-Ciel"},"establishments_count":2,"registry":{"corporate_purpose":"Travaux d'isolation thermique et acoustique.","fiscal_year_end":"3112","mission_company":false,"variable_capital":false},"latest_financials":{"fiscal_year_end":"2025-12-31","duration_months":12,"revenue":2450000,"net_income":132000,"equity":610000,"average_headcount":14,"revenue_growth_pct":8.2},"collective_procedure":null},"meta":{}}}}},"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"}}}}}}}}}},"/v1/companies/{siren}/establishments":{"get":{"operationId":"listCompanyEstablishments","summary":"List the establishments of a company","description":"Establishments of a company, open and closed: registered office first, then open ones, newest first. Each carries its address, NAF code, dates, position and the BDNB building it occupies when its address matches one.","tags":["Companies"],"parameters":[{"name":"siren","in":"path","required":true,"description":"SIREN of the company: 9 digits, no spaces. Example: 552100554.","schema":{"type":"string","pattern":"^\\d{9}$"}},{"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}}],"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/Establishment"}},"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]}],"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"}}}}}}},"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":"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":{"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"}}}}}}}}}},"/v1/companies/{siren}/officers":{"get":{"operationId":"listCompanyOfficers","summary":"List the officers of a company","description":"Officers registered at the RNE: people (with an id for GET /v1/officers/{id}) and corporate officers (with their SIREN when known). Management first, current mandates first. Empty for a company under partial diffusion.","tags":["Companies"],"parameters":[{"name":"siren","in":"path","required":true,"description":"SIREN of the company: 9 digits, no spaces. Example: 552100554.","schema":{"type":"string","pattern":"^\\d{9}$"}}],"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/CompanyOfficer"}},"meta":{"$ref":"#/components/schemas/PageMeta"}}},"example":{"data":[{"type":"person","id":"999100017a1b2c3d4","first_names":"Claire","last_name":"Montessuy","usage_name":null,"birth_month":"1971-06","role":"Président","active":true,"gabin_url":"https://gabin.ai/dirigeant/claire-montessuy-999100017a1b2c3d4"},{"type":"company","siren":"999100074","name":"Foncière Gratte-Ciel","role":"Commissaire aux comptes","active":true}],"meta":{"page":{"next_cursor":null,"limit":20},"total":2,"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"}}}}}}},"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":"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":{"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"}}}}}}}}}},"/v1/companies/{siren}/financials":{"get":{"operationId":"getCompanyFinancials","summary":"Get the annual accounts of a company","description":"Annual accounts filed at the RNE, one entry per fiscal year (up to 10, most recent first), with income statement and balance sheet items in euros, and a summary of the latest year. Many small companies file confidential or no accounts: `fiscal_years` can be empty.","tags":["Companies"],"parameters":[{"name":"siren","in":"path","required":true,"description":"SIREN of the company: 9 digits, no spaces. Example: 552100554.","schema":{"type":"string","pattern":"^\\d{9}$"}}],"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":"object","properties":{"siren":{"type":"string","description":"SIREN of the company."},"latest":{"anyOf":[{"type":"object","properties":{"fiscal_year_end":{"type":"string","description":"Closing date of the fiscal year (YYYY-MM-DD)."},"duration_months":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Length of the fiscal year, in months."},"revenue":{"description":"Revenue (chiffre d'affaires). In euros; null when not reported.","type":["number","null"]},"net_income":{"description":"Net income. In euros; null when not reported.","type":["number","null"]},"equity":{"description":"Shareholders' equity. In euros; null when not reported.","type":["number","null"]},"average_headcount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Average headcount reported."},"revenue_growth_pct":{"description":"Revenue change versus the previous fiscal year, in percent. Example: 12.5.","type":["number","null"]}},"required":["fiscal_year_end","duration_months","revenue","net_income","equity","average_headcount","revenue_growth_pct"],"description":"Latest filed accounts (summary, from the RNE accounts synthesis)."},{"type":"null"}],"description":"Summary of the latest fiscal year (RNE accounts synthesis), often present when `fiscal_years` is empty. Null when no accounts were filed."},"fiscal_years":{"type":"array","items":{"$ref":"#/components/schemas/FiscalYear"},"description":"Filed annual accounts, most recent first, up to 10. Consolidated accounts, banks and insurers are not included."}},"required":["siren","latest","fiscal_years"],"description":"Annual accounts filed at the RNE."},"meta":{"type":"object","description":"Empty for a single resource."}}},"example":{"data":{"siren":"999100017","latest":{"fiscal_year_end":"2025-12-31","duration_months":12,"revenue":2450000,"net_income":132000,"equity":610000,"average_headcount":14,"revenue_growth_pct":8.2},"fiscal_years":[]},"meta":{}}}}},"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":"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":{"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"}}}}}}}}}},"/v1/establishments/{siret}":{"get":{"operationId":"getEstablishment","summary":"Get an establishment","description":"One establishment by SIRET, with the name of its company. Next: GET /v1/companies/{siren} for the company.","tags":["Establishments"],"parameters":[{"name":"siret","in":"path","required":true,"description":"SIRET of the establishment: 14 digits (SIREN + 5). Example: 55210055400013.","schema":{"type":"string","pattern":"^\\d{14}$"}}],"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/EstablishmentDetail"},"meta":{"type":"object","description":"Empty for a single resource."}}},"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"},"meta":{}}}}},"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":"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":{"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"}}}}}}}}}},"/v1/officers":{"get":{"operationId":"searchOfficers","summary":"Search officers by name","description":"People holding a mandate in a French company, found by name in the RNE. Exact identities first; one company per person helps tell namesakes apart. Not paginated: refine `q` (first and last name) for more precise results. Next: GET /v1/officers/{id}.","tags":["Officers"],"parameters":[{"name":"q","in":"query","required":true,"description":"Last name, \"first last\" or \"last first\". Example: \"claire montessuy\".","schema":{"type":"string","minLength":2,"maxLength":80}},{"name":"limit","in":"query","required":false,"description":"Maximum results, 1 to 20. Default 8. Exact identities come first.","schema":{"default":8,"type":"integer","minimum":1,"maximum":20}}],"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/OfficerSummary"}},"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"}}}}}}}}}},"/v1/officers/{id}":{"get":{"operationId":"getOfficer","summary":"Get an officer","description":"An officer (person) by id: mandates in every company where the same identity (name, first names, birth month) appears, and a bounded relationship graph (their companies and the other officers of those companies). Companies under partial diffusion are never linked to a person.","tags":["Officers"],"parameters":[{"name":"id","in":"path","required":true,"description":"Officer id: SIREN of one of their mandates + 8 hex characters. Stable for the same person. Example: \"552100554a1b2c3d4\".","schema":{"type":"string","pattern":"^\\d{9}[0-9a-fA-F]{8}$"}}],"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/Officer"},"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"}}}}}}}}}},"/v1/naf":{"get":{"operationId":"listNaf","summary":"List NAF activities","description":"NAF rev. 2 sub-classes (732), the activity level SIRENE stores, with their hierarchy and Gabin sector. Filter by words of the label or start of the code (`q`) and by section. Codes go into the `naf` filter of GET /v1/companies (divisions and sections are accepted there too).","tags":["Reference data"],"parameters":[{"name":"q","in":"query","required":false,"description":"Words of the label or start of the code, accents ignored. Example: \"boulangerie\", \"43.2\".","schema":{"type":"string","maxLength":80}},{"name":"section","in":"query","required":false,"description":"NAF section letter. Example: \"F\".","schema":{"type":"string","pattern":"^[A-Ua-u]$"}}],"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/NafActivity"}},"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"}}}}}}}}}},"/v1/naf/{code}":{"get":{"operationId":"getNaf","summary":"Get a NAF activity","description":"One NAF rev. 2 sub-class with its class, group, division, section and Gabin sector.","tags":["Reference data"],"parameters":[{"name":"code","in":"path","required":true,"description":"NAF rev. 2 sub-class, with or without dot, any case. Example: \"10.71C\" or \"1071c\".","schema":{"type":"string","maxLength":8}}],"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/NafActivity"},"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"}}}}}}}}}},"/v1/legal-forms":{"get":{"operationId":"listLegalForms","summary":"List legal form families","description":"Legal form families accepted by the `legal_form` filter of GET /v1/companies. Each family groups INSEE legal categories (SAS covers SAS and SASU, etc.).","tags":["Reference data"],"parameters":[],"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/LegalForm"}},"meta":{"$ref":"#/components/schemas/PageMeta"}}}}}},"400":{"description":"PAGINATION_LIMIT","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"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"}}}}}}}}}},"/v1/headcount-ranges":{"get":{"operationId":"listHeadcountRanges","summary":"List headcount ranges","description":"INSEE headcount ranges (tranches d'effectif salarié) with their bounds. Codes go into the `headcount` filter of GET /v1/companies and appear as `headcount_range` on companies.","tags":["Reference data"],"parameters":[],"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/HeadcountRange"}},"meta":{"$ref":"#/components/schemas/PageMeta"}}}}}},"400":{"description":"PAGINATION_LIMIT","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"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"}}}}}}}}}},"/v1/me":{"get":{"operationId":"getMe","summary":"Get the current account","description":"The account and credential behind the bearer, the plan, the per-minute rate limit and the daily quota with what remains after this call, and today's recorded usage. Useful to check a key.","tags":["Account"],"parameters":[],"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/Me"},"meta":{"type":"object","description":"Empty for a single resource."}}}}}},"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"}}}}}}}}}},"/v1/health":{"get":{"operationId":"getHealth","summary":"Service status","description":"`ok` when the API and its database answer. No authentication, no quota.","tags":["Meta"],"security":[],"parameters":[],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"],"description":"`degraded`: the database does not answer."},"version":{"type":"string","const":"v1"}},"required":["status","version"],"description":"Service status. No authentication required."},"meta":{"type":"object","description":"Empty for a single resource."}}}}}}}}},"/v1/buildings":{"get":{"operationId":"listBuildings","summary":"Search buildings in an area","description":"Buildings (BDNB) in one area, ordered by id: a bounding box (`bbox`, at most 4 km²), a circle (`lat`, `lon`, `radius` up to 1,000 m), a city (`insee`) or a district (`iris`). Optional filters: `usage`, `built_after`, `built_before`, `dpe`, `min_companies`.\n\n`format=geojson` returns a GeoJSON FeatureCollection in `data` (points, or footprints with `geometry=footprint`), 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. A filtered search over a large city can take too long (`TIMEOUT`): use a bbox or a district. To draw many buildings on a map, use GET /v1/tiles/buildings/{z}/{x}/{y}.pbf. Next: GET /v1/buildings/{id}.","tags":["Buildings"],"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":"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":"usage","in":"query","required":false,"description":"Main uses, comma-separated: residential, tertiary, industrial, mixed. Example: \"residential,mixed\".","schema":{"type":"string","maxLength":80}},{"name":"built_after","in":"query","required":false,"description":"Built in or after this year. Example: 1990.","schema":{"type":"integer","minimum":1000,"maximum":2100}},{"name":"built_before","in":"query","required":false,"description":"Built in or before this year. Example: 1974.","schema":{"type":"integer","minimum":1000,"maximum":2100}},{"name":"dpe","in":"query","required":false,"description":"Energy classes, comma-separated. Example: \"F,G\".","schema":{"type":"string","maxLength":20}},{"name":"min_companies","in":"query","required":false,"description":"At least this many linked companies (same count as `companies_count`). Example: 1.","schema":{"type":"integer","minimum":1,"maximum":1000}},{"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"]}},{"name":"geometry","in":"query","required":false,"description":"With `format=geojson`: `point` (default, the building center) or `footprint` (polygon).","schema":{"default":"point","type":"string","enum":["point","footprint"]}}],"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/BuildingSummary"}},{"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.id`."},"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/BuildingSummary"}},"required":["type","id","geometry","properties"]}}},"required":["type","features"],"description":"Buildings as a GeoJSON FeatureCollection; `properties` is a building summary."}],"description":"A list of building summaries, or a FeatureCollection with `format=geojson`."},"meta":{"$ref":"#/components/schemas/PageMeta"}}},"example":{"data":[{"id":"bdnb-bg-CJ69-HW8G-PTTG","gabin_url":"https://gabin.ai/batiment/40-rue-de-bruxelles-69100-villeurbanne-bdnb-bg-CJ69-HW8G-PTTG","address":"40 Rue de Bruxelles, 69100 Villeurbanne","insee":"69266","iris":"692660101","usage":"residential","construction_year":1934,"levels":7,"housing_units":42,"ground_area_m2":612,"dpe_class":"D","companies_count":2,"center":[4.8795,45.7665]}],"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 (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"}}}}}}}}}},"/v1/buildings/{id}":{"get":{"operationId":"getBuilding","summary":"Get a building","description":"Profile of a building (BDNB) by id: name of the place, addresses, city and district, use, construction year, levels, dwellings, footprint, energy class, and the number of linked companies.\n\nFind ids with GET /v1/buildings (area search), GET /v1/geocode (address) or GET /v1/places (named place). Next: `/companies` and the sections `/energy`, `/transactions`, `/owners`, `/condominium`, `/parcels`, `/parking`, `/permits`, `/fiber`, `/planning`, `/market` under the same path.","tags":["Buildings"],"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/Building"},"meta":{"type":"object","description":"Empty for a single resource."}}},"example":{"data":{"id":"bdnb-bg-CJ69-HW8G-PTTG","gabin_url":"https://gabin.ai/batiment/40-rue-de-bruxelles-69100-villeurbanne-bdnb-bg-CJ69-HW8G-PTTG","name":null,"address":"40 Rue de Bruxelles, 69100 Villeurbanne","other_addresses":["2 Rue Racine, 69100 Villeurbanne"],"postal_code":"69100","insee":"69266","city":{"insee":"69266","name":"Villeurbanne","department":"69"},"district":{"iris":"692660101","name":"Gratte-Ciel"},"usage":"residential","construction_year":1934,"levels":7,"housing_units":42,"ground_area_m2":612,"dpe_class":"D","height_m":21.5,"heating_energy":"Gaz","center":[4.8795,45.7665],"footprint":{"type":"Polygon","coordinates":[[[4.8792,45.7663],[4.8798,45.7663],[4.8798,45.7667],[4.8792,45.7667],[4.8792,45.7663]]]},"companies_count":6,"companies_count_capped":false},"meta":{}}}}},"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"}}}}}}}}}},"/v1/buildings/{id}/companies":{"get":{"operationId":"listBuildingCompanies","summary":"List the companies linked to a building","description":"Companies linked to a building: occupants (an establishment located there, matched by address or position) and corporate owners (land files), merged by SIREN. Active companies first, then by name.\n\nSole proprietorships (entrepreneurs individuels) are listed as occupants by their registered name; companies under partial diffusion never are. Up to 500 companies can be reached; above 100 linked companies, the address is usually a business domiciliation.","tags":["Buildings"],"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})*$"}},{"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}}],"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/BuildingCompany"}},"meta":{"$ref":"#/components/schemas/PageMeta"}}},"example":{"data":[{"company":{"siren":"999100017","name":"Atelier Thermique du Rhône","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"},"latest_revenue":null,"latest_revenue_year_end":null},"roles":["occupant"],"establishment":{"siret":"99910001700011","headquarters":true,"trade_name":null,"naf_code":"43.29A","naf_label":"Travaux d'isolation","active":true}}],"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"}}}}}}},"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"}}}}}}}}}},"/v1/buildings/{id}/energy":{"get":{"operationId":"getBuildingEnergy","summary":"Get the energy certificates of a building","description":"Energy performance certificates (DPE, ADEME) attached to the building in the BDNB: representative class, class distribution, housing and tertiary certificates with consumption, emissions, heating, insulation.","tags":["Buildings"],"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/BuildingEnergy"},"meta":{"type":"object","description":"Empty for a single resource."}}},"example":{"data":{"representative_class":"D","class_distribution":{"A":0,"B":1,"C":4,"D":12,"E":6,"F":2,"G":1},"housing_certificates":[],"commercial_certificates":[],"housing_count":26,"commercial_count":0},"meta":{}}}}},"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"}}}}}}}}}},"/v1/buildings/{id}/transactions":{"get":{"operationId":"getBuildingTransactions","summary":"Get the property transactions of a building","description":"Property sales (DVF, DGFiP) on the building's cadastral parcels since 2014: date, nature, price, lots, land, median price per m². DVF names no party to a sale.","tags":["Buildings"],"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/BuildingTransactions"},"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"}}}}}}}}}},"/v1/buildings/{id}/owners":{"get":{"operationId":"getBuildingOwners","summary":"Get the corporate owners of a building","description":"Owners of the building that are legal entities (land files: BDNB and MAJIC), the one holding the most first, with their holdings, property-manager signals, and occupants that look like the owner (`likely_owner`, an inference; sole proprietorships included under their registered name).","tags":["Buildings"],"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/BuildingOwners"},"meta":{"type":"object","description":"Empty for a single resource."}}},"example":{"data":{"items":[{"siren":"999100074","name":"Foncière des Gratte-Ciel","company":{"siren":"999100074","name":"Foncière des 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"},"latest_revenue":null,"latest_revenue_year_end":null},"units_owned":3,"holdings":[{"type":"unit","floor":"00","entrance":null,"right":"P","owner_group":"0","land_use":null}],"property_manager":null,"likely_owner":null,"sources":["bdnb","majic"]}],"parcels":["69266000AB0001"]},"meta":{}}}}},"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"}}}}}}}}}},"/v1/buildings/{id}/condominium":{"get":{"operationId":"getBuildingCondominium","summary":"Get the condominium of a building","description":"Registered condominium of the building (RNIC): lots, construction period, type of manager and the professional manager (syndic) when it is a legal entity. A volunteer manager is an individual and is never named.","tags":["Buildings"],"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/BuildingCondominium"},"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"}}}}}}}}}},"/v1/buildings/{id}/parcels":{"get":{"operationId":"getBuildingParcels","summary":"Get the cadastral parcels of a building","description":"Cadastral parcels under the building, main one first, with area and GeoJSON boundary. Details of a parcel: GET /v1/parcels/{id}.","tags":["Buildings"],"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/BuildingParcels"},"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"}}}}}}}}}},"/v1/buildings/{id}/parking":{"get":{"operationId":"getBuildingParking","summary":"Get the parking of a building","description":"Parking of the building: condominium parking lots (RNIC), garage lots (BDNB), OpenStreetMap parkings intersecting or within 50 m, EV charging stations nearby (IRVE).","tags":["Buildings"],"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/BuildingParking"},"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"}}}}}}}}}},"/v1/buildings/{id}/permits":{"get":{"operationId":"getBuildingPermits","summary":"Get the building permits of a building","description":"Building permits (Sitadel) on the building's parcels, most recent first: type, status, dates, dwellings and areas created. The applicant is given only when it is a legal entity.","tags":["Buildings"],"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/BuildingPermits"},"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"}}}}}}}}}},"/v1/buildings/{id}/fiber":{"get":{"operationId":"getBuildingFiber","summary":"Get the fiber deployment of a building","description":"Fiber deployment status of the building (Arcep): status, building access points (IMB), infrastructure operator, retail offers.","tags":["Buildings"],"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/BuildingFiber"},"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"}}}}}}}}}},"/v1/buildings/{id}/planning":{"get":{"operationId":"getBuildingPlanning","summary":"Get the urban planning rules of a building","description":"Urban planning of the building (Géoportail de l'Urbanisme): local plan zone (PLU) with its regulation, safeguard plan (PSMV), heritage easements (historic monuments and their surroundings, remarkable sites).","tags":["Buildings"],"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/BuildingPlanning"},"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"}}}}}}}}}},"/v1/buildings/{id}/market":{"get":{"operationId":"getBuildingMarket","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.","tags":["Buildings"],"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"}}}}}}}}}},"/v1/companies/{siren}/buildings":{"get":{"operationId":"listCompanyBuildings","summary":"List the buildings of a company","description":"Buildings a company occupies (its establishments matched to a BDNB building, open or closed) and owns (land files, BDNB), merged by building: occupied and owned first, then by open establishments.\n\nLegal entities only: the list is empty for a sole proprietorship or a company under partial diffusion. Up to 1,000 buildings are read per role. Next: GET /v1/buildings/{id}.","tags":["Companies"],"parameters":[{"name":"siren","in":"path","required":true,"description":"SIREN of the company: 9 digits, no spaces. Example: 552100554.","schema":{"type":"string","pattern":"^\\d{9}$"}},{"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}}],"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/CompanyBuilding"}},"meta":{"$ref":"#/components/schemas/PageMeta"}}},"example":{"data":[{"building":{"id":"bdnb-bg-CJ69-HW8G-PTTG","gabin_url":"https://gabin.ai/batiment/40-rue-de-bruxelles-69100-villeurbanne-bdnb-bg-CJ69-HW8G-PTTG","address":"40 Rue de Bruxelles, 69100 Villeurbanne","insee":"69266","iris":"692660101","usage":"residential","construction_year":1934,"levels":7,"housing_units":42,"ground_area_m2":612,"dpe_class":"D","companies_count":2,"center":[4.8795,45.7665]},"roles":["occupant","owner"],"establishments":["99910001700011"],"active_establishments":1,"units_owned":3}],"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"}}}}}}},"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"}}}}}}}}}},"/v1/parcels/{id}":{"get":{"operationId":"getParcel","summary":"Get a cadastral parcel","description":"A cadastral parcel by id: section, number, area, GeoJSON boundary, city, district and the buildings standing on it. Owners are not listed here (corporate owners: GET /v1/buildings/{id}/owners). Parcel ids come from GET /v1/buildings/{id}/parcels or the parcels tile layer.","tags":["Parcels"],"parameters":[{"name":"id","in":"path","required":true,"description":"Cadastral parcel id (14 characters: INSEE code, prefix, section, number). Example: \"69266000AB0123\".","schema":{"type":"string","pattern":"^(\\d{5}|2[AB]\\d{3})[0-9A-Z]{9}$"}}],"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/Parcel"},"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":"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":{"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"}}}}}}}}}},"/v1/geocode":{"get":{"operationId":"geocodeAddress","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}.","tags":["Addresses"],"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"}}}}}}}}}},"/v1/places":{"get":{"operationId":"searchPlaces","summary":"Search named places","description":"Named places (residences, hospitals, schools, care homes, hotels…) by name, from the BD TOPO, the condominium register and other public sources, each with its building. A city at the end narrows the search (\"orangerie ecully\"). Next: GET /v1/buildings/{building_id}.","tags":["Addresses"],"parameters":[{"name":"q","in":"query","required":true,"description":"Name of a place, optionally followed by its city. Example: \"hopital edouard herriot lyon\".","schema":{"type":"string","minLength":4,"maxLength":120}},{"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/Place"}},"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":"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":{"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"}}}}}}}}}},"/v1/zones/cities":{"get":{"operationId":"searchCities","summary":"Search cities","description":"Cities and arrondissements of Paris, Lyon and Marseille by name (prefix), postal code or INSEE code, up to 8. Next: GET /v1/zones/cities/{insee}, or use `insee` in GET /v1/buildings and GET /v1/companies.","tags":["Zones"],"parameters":[{"name":"q","in":"query","required":true,"description":"City name (prefix), postal code or INSEE code. Example: \"villeurb\", \"69100\".","schema":{"type":"string","minLength":2,"maxLength":60}}],"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/City"}},"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":"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":{"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"}}}}}}}}}},"/v1/zones/cities/{insee}":{"get":{"operationId":"getCity","summary":"Get a city","description":"A city or arrondissement by INSEE code: name, department, main postal code, population, center. Next: its districts, GET /v1/zones/city/{insee}/market, or `insee` in GET /v1/buildings.","tags":["Zones"],"parameters":[{"name":"insee","in":"path","required":true,"description":"INSEE code of a city or arrondissement. Example: \"69266\".","schema":{"type":"string","pattern":"^(\\d{5}|2[AB]\\d{3})$"}}],"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/City"},"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":"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":{"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"}}}}}}}}}},"/v1/zones/cities/{insee}/districts":{"get":{"operationId":"listCityDistricts","summary":"List the districts of a city","description":"Districts of a city, by name: one or several merged IRIS with a readable name. Use the `iris` code in GET /v1/buildings, GET /v1/companies or GET /v1/zones/district/{iris}/market.","tags":["Zones"],"parameters":[{"name":"insee","in":"path","required":true,"description":"INSEE code of a city or arrondissement. Example: \"69266\".","schema":{"type":"string","pattern":"^(\\d{5}|2[AB]\\d{3})$"}}],"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/District"}},"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"}}}}}}},"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":"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":{"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"}}}}}}}}}},"/v1/zones/districts/{iris}":{"get":{"operationId":"getDistrict","summary":"Get a district","description":"A district by IRIS code: its readable name and city. Next: GET /v1/buildings?iris={iris}, GET /v1/companies?iris={iris} or GET /v1/zones/district/{iris}/market.","tags":["Zones"],"parameters":[{"name":"iris","in":"path","required":true,"description":"IRIS code of a district (9 characters). Example: \"692660101\".","schema":{"type":"string","pattern":"^(\\d{5}|2[AB]\\d{3})\\d{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/District"},"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":"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":{"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"}}}}}}}}}},"/v1/zones/departments/{code}/cities":{"get":{"operationId":"listDepartmentCities","summary":"List the cities of a department","description":"All cities of a department by name, with the arrondissements of Paris, Lyon and Marseille listed next to their city. Not paginated.","tags":["Zones"],"parameters":[{"name":"code","in":"path","required":true,"description":"Department code. Example: \"69\", \"2A\", \"974\".","schema":{"type":"string","pattern":"^(\\d{2,3}|2[AB])$"}}],"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/DepartmentCity"}},"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"}}}}}}},"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":"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":{"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"}}}}}}}}}},"/v1/zones/{level}/{code}/market":{"get":{"operationId":"getZoneMarket","summary":"Get the market figures of a zone","description":"Market and territory figures of a zone, at every level containing it: sale prices per m² by segment (DVF), most active streets, rents (ANIL), population by age and occupation (INSEE census), income (FiLoSoFi). A family missing for a zone comes back empty.","tags":["Zones"],"parameters":[{"name":"level","in":"path","required":true,"description":"Zone level: `region`, `department`, `city` (or arrondissement), `district`.","schema":{"type":"string","enum":["region","department","city","district"]}},{"name":"code","in":"path","required":true,"description":"Code of the zone: region code (\"84\"), department (\"69\"), INSEE (\"69266\") or IRIS (\"692660101\").","schema":{"type":"string","pattern":"^[0-9AB]{2,9}$"}}],"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/ZoneMarket"},"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":"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":{"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"}}}}}}}}}},"/v1/zones/{level}/{code}/boundary":{"get":{"operationId":"getZoneBoundary","summary":"Get the boundary of a zone","description":"Simplified boundary of a zone (region, department, city, district) as a GeoJSON Polygon or MultiPolygon, WGS84, to draw it on a map or to derive a bbox.","tags":["Zones"],"parameters":[{"name":"level","in":"path","required":true,"description":"Zone level: `region`, `department`, `city` (or arrondissement), `district`.","schema":{"type":"string","enum":["region","department","city","district"]}},{"name":"code","in":"path","required":true,"description":"Code of the zone: region code (\"84\"), department (\"69\"), INSEE (\"69266\") or IRIS (\"692660101\").","schema":{"type":"string","pattern":"^[0-9AB]{2,9}$"}}],"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":"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."},"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":"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":{"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"}}}}}}}}}},"/v1/search/fields":{"get":{"operationId":"listSearchFields","summary":"List the fields of the multi-criteria search","description":"Catalog of the fields usable in POST /v1/search and POST /v1/search/count: id, target, type, operator, unit, accepted values, source table. Labels and descriptions are in French; ids and codes are stable.\n\nA 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`.\n\nExample: {\"target\": \"buildings\", \"zone\": {\"type\": \"city\", \"code\": \"69266\"}, \"conditions\": [{\"field\": \"batiment.annee_construction\", \"max\": 1974}, {\"field\": \"dpe.classe\", \"values\": [\"F\", \"G\"]}]}","tags":["Search"],"parameters":[{"name":"target","in":"query","required":false,"description":"Only the fields of this target.","schema":{"type":"string","enum":["buildings","companies"]}}],"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/SearchField"}},"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"}}}}}}}}}},"/v1/search/count":{"post":{"operationId":"countSearch","summary":"Count the results of a multi-criteria search","description":"Counts the buildings or companies matching a search (up to 100,000) and breaks them down (use, energy class, city…). Use it to refine a search before listing it with POST /v1/search.\n\nA 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`.\n\nExample: {\"target\": \"buildings\", \"zone\": {\"type\": \"city\", \"code\": \"69266\"}, \"conditions\": [{\"field\": \"batiment.annee_construction\", \"max\": 1974}, {\"field\": \"dpe.classe\", \"values\": [\"F\", \"G\"]}]}\n\nWeight: 5 (counts 5× against the rate limit and the daily quota).","tags":["Search"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchFilters"}}}},"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/SearchCount"},"meta":{"type":"object","description":"Empty for a single resource."}}}}}},"400":{"description":"ZONE_REQUIRED, INVALID","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"}}}}}}},"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"}}}}}}}}}},"/v1/search":{"post":{"operationId":"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.\n\nA 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`.\n\nExample: {\"target\": \"buildings\", \"zone\": {\"type\": \"city\", \"code\": \"69266\"}, \"conditions\": [{\"field\": \"batiment.annee_construction\", \"max\": 1974}, {\"field\": \"dpe.classe\", \"values\": [\"F\", \"G\"]}]}\n\nWeight: 5 (counts 5× against the rate limit and the daily quota).","tags":["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"}}}}}}}}}},"/v1/tiles/{layer}/{z}/{x}/{y}.pbf":{"get":{"operationId":"getTile","summary":"Get a vector tile","description":"A Mapbox Vector Tile (MVT, XYZ scheme) of a gabin.ai map layer, for MapLibre GL or Mapbox GL (send the key with `transformRequest`). 204 when the tile is empty. Feature properties are those of the gabin.ai map (ids such as `batiment_groupe_id`, `parcelle_id` open the matching endpoints).\n\nWeight: 0.1 for a tile served from the server cache (10 min), 0.5 for a tile read from the database.\n\nLayers, zoom ranges and query options (layer filters, passed as-is; unknown keys are ignored):\n- `buildings`: zoom 15–16; options `acceslibre`, `friche`, `parking` (true/false: extra properties)\n- `parcels`: zoom 15–16\n- `districts`: zoom 10–13\n- `owners`: zoom 15–16; options `iris`, `commune` (INSEE) or `cp` (postal code)\n- `occupants`: zoom 15–16; options `iris`, `commune` or `cp`\n- `condominiums`: zoom 15–16; options `iris`, `commune` or `cp`\n- `fiber`: zoom 15–16\n- `transactions`: zoom 15–16; options `iris`/`commune`/`cp`, `prix_min`, `prix_max`, `date_min`, `date_max` (YYYY-MM-DD), `type_local`, `vente_multilot`, `surface_min`, `surface_max`, `pieces_min`, `pieces_max`\n- `energy`: zoom 15–16; options `iris`/`commune`/`cp`, `etiquettes` (A,B…), `date_min`, `date_max`, `jeux`, `type_batiment`, `surface_min`, `surface_max`, `generateur`, `isolation`\n- `market`: zoom 0–22; options `metric` (price, rent, demography or income metric id)\n- `planning`: zoom 13–22; options `view` (`zones` or `friches`)\n- `permits`: zoom 15–16; options `type`, `statut`, `annee_min`, `annee_max`\n- `heritage`: zoom 13–22; options `kinds` (monument, abords, spr, site), `perimetres` (true/false), `iris`/`commune`/`cp`\n- `ev_charging`: zoom 12–15\n- `parking`: zoom 13–15","tags":["Tiles"],"parameters":[{"name":"layer","in":"path","required":true,"description":"Layer name. See the endpoint description for zoom ranges and options.","schema":{"type":"string","enum":["buildings","parcels","districts","owners","occupants","condominiums","fiber","transactions","energy","market","planning","permits","heritage","ev_charging","parking"]}},{"name":"z","in":"path","required":true,"description":"Zoom level (0 to 22).","schema":{"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"x","in":"path","required":true,"description":"Tile column (XYZ scheme).","schema":{"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"y","in":"path","required":true,"description":"Tile row (XYZ scheme).","schema":{"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Mapbox Vector Tile (protobuf); 204 when empty.","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/vnd.mapbox-vector-tile":{"schema":{"type":"string","format":"binary"}}}},"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"}}}}}}},"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"}}}}}}}}}},"/v1/openapi.json":{"get":{"operationId":"getOpenApi","summary":"OpenAPI document","description":"This document: OpenAPI 3.1 description of every v1 endpoint. No authentication.","tags":["Meta"],"security":[],"parameters":[],"responses":{"200":{"description":"OpenAPI 3.1 document.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key `gab_live_…` or OAuth access token `gat_…`."}},"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":{"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`."},"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."},"Company":{"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."},"acronym":{"description":"Acronym (sigle) when declared.","type":["string","null"]},"sole_proprietorship":{"type":"boolean","description":"True when the legal unit is a natural person (entrepreneur individuel)."},"legal_form":{"type":"object","properties":{"code":{"description":"INSEE legal category code. Example: \"5710\".","type":["string","null"]},"label":{"type":"string","description":"INSEE label of the legal form, in French."}},"required":["code","label"]},"naf_section":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]},{"type":"null"}],"description":"NAF section of the activity. Example: {\"code\": \"F\", \"label\": \"Construction\"}."},"headcount_range":{"type":"object","properties":{"code":{"type":"string","enum":["11","12","21","22","31","32","41","42","51","52","53","NN","00","01","02","03"],"description":"INSEE headcount range code."},"label":{"type":"string","description":"Label, in French. Example: \"10 à 19 salariés\"."}},"required":["code","label"]},"category":{"anyOf":[{"type":"string","enum":["PME","ETI","GE"]},{"type":"null"}],"description":"INSEE company size category: PME (SME), ETI (mid-cap), GE (large)."},"social_economy":{"type":"boolean","description":"Member of the social and solidarity economy (ESS)."},"share_capital":{"description":"Share capital declared at the RNE. In euros; null when not reported.","type":["number","null"]},"vat_number":{"description":"Intra-EU VAT number computed from the SIREN. Example: \"FR58999722432\".","type":["string","null"]},"headquarters":{"anyOf":[{"$ref":"#/components/schemas/Establishment"},{"type":"null"}],"description":"Registered office."},"city":{"anyOf":[{"type":"object","properties":{"insee":{"type":"string"},"name":{"type":"string"},"department":{"type":"string"}},"required":["insee","name","department"]},{"type":"null"}],"description":"City of the registered office."},"district":{"anyOf":[{"type":"object","properties":{"iris":{"type":"string"},"name":{"type":"string"}},"required":["iris","name"]},{"type":"null"}],"description":"District (IRIS) of the registered office, only when its position is known at street level."},"establishments_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of establishments, open and closed."},"registry":{"anyOf":[{"type":"object","properties":{"corporate_purpose":{"description":"Corporate purpose from the articles (objet social), in French.","type":["string","null"]},"fiscal_year_end":{"description":"Day and month of the fiscal year end, \"DDMM\". Example: \"3112\".","type":["string","null"]},"mission_company":{"type":"boolean","description":"Société à mission."},"variable_capital":{"type":"boolean","description":"Variable share capital."}},"required":["corporate_purpose","fiscal_year_end","mission_company","variable_capital"]},{"type":"null"}],"description":"Facts filed at the RNE (national business register); null when unknown or under partial diffusion."},"latest_financials":{"anyOf":[{"type":"object","properties":{"fiscal_year_end":{"type":"string","description":"Closing date of the fiscal year (YYYY-MM-DD)."},"duration_months":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Length of the fiscal year, in months."},"revenue":{"description":"Revenue (chiffre d'affaires). In euros; null when not reported.","type":["number","null"]},"net_income":{"description":"Net income. In euros; null when not reported.","type":["number","null"]},"equity":{"description":"Shareholders' equity. In euros; null when not reported.","type":["number","null"]},"average_headcount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Average headcount reported."},"revenue_growth_pct":{"description":"Revenue change versus the previous fiscal year, in percent. Example: 12.5.","type":["number","null"]}},"required":["fiscal_year_end","duration_months","revenue","net_income","equity","average_headcount","revenue_growth_pct"],"description":"Latest filed accounts (summary, from the RNE accounts synthesis)."},{"type":"null"}]},"collective_procedure":{"anyOf":[{"type":"object","properties":{"ongoing":{"type":"boolean","description":"True while the procedure is open."},"nature":{"description":"Nature as published in the BODACC, in French. Example: \"Redressement judiciaire\".","type":["string","null"]},"date":{"description":"Date of the judgment (YYYY-MM-DD).","type":["string","null"]}},"required":["ongoing","nature","date"]},{"type":"null"}],"description":"Latest collective insolvency procedure published in the BODACC; null when none."}},"required":["siren","name","naf_code","naf_label","sector","created_on","active","partial_diffusion","gabin_url","acronym","sole_proprietorship","legal_form","naf_section","headcount_range","category","social_economy","share_capital","vat_number","headquarters","city","district","establishments_count","registry","latest_financials","collective_procedure"],"description":"A company (SIRENE legal unit) with its registered office, registry facts and latest accounts."},"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":"INSEE label of the legal form, in French. Example: \"SAS, société par actions simplifiée\".","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\"."}},"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."},"Establishment":{"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."}},"required":["siret","siren","headquarters","trade_name","address","postal_code","city","insee","naf_code","created_on","closed_on","active","building_id","location"],"description":"An establishment (SIRENE). Under partial diffusion: no trade name, no street, no position, no building."},"CompanyOfficer":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"person"},"id":{"type":"string","description":"Officer id, for GET /v1/officers/{id}."},"first_names":{"type":"string","description":"First names as registered. Example: \"Claire\"."},"last_name":{"type":"string","description":"Birth (legal) last name. Example: \"Montessuy\"."},"usage_name":{"description":"Usage name declared at the RNE when it differs.","type":["string","null"]},"birth_month":{"description":"Month and year of birth as published by the RNE, YYYY-MM (the register gives no day). Tells namesakes apart. Example: \"1949-03\". Null when the register has none.","type":["string","null"]},"role":{"type":"string","description":"Role, in French. Example: \"Président\"."},"active":{"type":"boolean","description":"False for a past mandate still published by the register."},"gabin_url":{"type":"string","description":"Page of the officer on gabin.ai."}},"required":["type","id","first_names","last_name","usage_name","birth_month","role","active","gabin_url"]},{"type":"object","properties":{"type":{"type":"string","const":"company"},"siren":{"description":"SIREN of the corporate officer when known.","type":["string","null"]},"name":{"type":"string","description":"Name of the corporate officer."},"role":{"type":"string","description":"Role, in French. Example: \"Commissaire aux comptes\"."},"active":{"type":"boolean","description":"False for a past mandate still published by the register."}},"required":["type","siren","name","role","active"]}],"description":"An officer of a company: a person or a company (corporate officer)."},"FiscalYear":{"type":"object","properties":{"fiscal_year_end":{"type":"string","description":"Closing date of the fiscal year (YYYY-MM-DD)."},"duration_months":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Length of the fiscal year, in months."},"format":{"type":"string","enum":["full","simplified"],"description":"`full`: liasse 2050-2059. `simplified`: liasse 2033 (fewer items)."},"confidential":{"type":"boolean","description":"True when the income statement was filed as confidential: balance sheet items only."},"revenue":{"description":"Revenue (chiffre d'affaires). In euros; null when not reported.","type":["number","null"]},"export_revenue":{"description":"Revenue from exports. In euros; null when not reported.","type":["number","null"]},"gross_margin":{"description":"Gross margin (marge brute). In euros; null when not reported.","type":["number","null"]},"value_added":{"description":"Value added (valeur ajoutée). In euros; null when not reported.","type":["number","null"]},"ebitda":{"description":"Gross operating surplus (EBE, excédent brut d'exploitation), close to EBITDA. In euros; null when not reported.","type":["number","null"]},"operating_income":{"description":"Operating income (résultat d'exploitation). In euros; null when not reported.","type":["number","null"]},"net_income":{"description":"Net income (résultat net). In euros; null when not reported.","type":["number","null"]},"purchases_and_external_charges":{"description":"Purchases consumed and external charges. In euros; null when not reported.","type":["number","null"]},"inventory":{"description":"Inventory (stocks). In euros; null when not reported.","type":["number","null"]},"trade_receivables":{"description":"Trade receivables (créances clients). In euros; null when not reported.","type":["number","null"]},"trade_payables":{"description":"Trade payables (dettes fournisseurs). In euros; null when not reported.","type":["number","null"]},"operating_working_capital_need":{"description":"Operating working capital requirement (BFR d'exploitation). In euros; null when not reported.","type":["number","null"]},"non_operating_working_capital_need":{"description":"Non-operating working capital requirement (BFR hors exploitation). In euros; null when not reported.","type":["number","null"]},"working_capital":{"description":"Working capital (fonds de roulement). In euros; null when not reported.","type":["number","null"]},"cash":{"description":"Cash (trésorerie). In euros; null when not reported.","type":["number","null"]},"financial_debt":{"description":"Financial debt (dettes financières). In euros; null when not reported.","type":["number","null"]},"equity":{"description":"Shareholders' equity (fonds propres). In euros; null when not reported.","type":["number","null"]},"total_assets":{"description":"Balance sheet total. In euros; null when not reported.","type":["number","null"]},"headcount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Average headcount reported in the filing."},"payroll":{"description":"Wages and social charges. In euros; null when not reported.","type":["number","null"]},"taxes":{"description":"Taxes and duties (impôts et taxes). In euros; null when not reported.","type":["number","null"]}},"required":["fiscal_year_end","duration_months","format","confidential","revenue","export_revenue","gross_margin","value_added","ebitda","operating_income","net_income","purchases_and_external_charges","inventory","trade_receivables","trade_payables","operating_working_capital_need","non_operating_working_capital_need","working_capital","cash","financial_debt","equity","total_assets","headcount","payroll","taxes"],"description":"One fiscal year of filed annual accounts. Null amounts: item absent from the filing."},"EstablishmentDetail":{"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)."}},"required":["siret","siren","headquarters","trade_name","address","postal_code","city","insee","naf_code","created_on","closed_on","active","building_id","location","company_name"],"description":"An establishment and the name of its company."},"OfficerSummary":{"type":"object","properties":{"id":{"type":"string","description":"Officer id, for GET /v1/officers/{id}."},"first_names":{"type":"string","description":"First names as registered. Example: \"Claire\"."},"last_name":{"type":"string","description":"Birth (legal) last name. Example: \"Montessuy\"."},"usage_name":{"description":"Usage name declared at the RNE when it differs.","type":["string","null"]},"birth_month":{"description":"Month and year of birth as published by the RNE, YYYY-MM (the register gives no day). Tells namesakes apart. Example: \"1949-03\". Null when the register has none.","type":["string","null"]},"company_name":{"type":"string","description":"One company where the person holds a mandate, to tell namesakes apart."},"role":{"type":"string","description":"Role in that company, in French."},"gabin_url":{"type":"string","description":"Page of the officer on gabin.ai."}},"required":["id","first_names","last_name","usage_name","birth_month","company_name","role","gabin_url"],"description":"An officer found by name."},"Officer":{"type":"object","properties":{"id":{"type":"string","description":"Officer id."},"first_names":{"type":"string","description":"First names as registered. Example: \"Claire\"."},"last_name":{"type":"string","description":"Birth (legal) last name. Example: \"Montessuy\"."},"usage_name":{"description":"Usage name declared at the RNE when it differs.","type":["string","null"]},"birth_month":{"description":"Month and year of birth as published by the RNE, YYYY-MM (the register gives no day). Tells namesakes apart. Example: \"1949-03\". Null when the register has none.","type":["string","null"]},"mandates":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","description":"Role, in French."},"active":{"type":"boolean","description":"False for a past mandate."},"company":{"$ref":"#/components/schemas/CompanySummary"}},"required":["role","active","company"]},"description":"Mandates in all companies where the same identity appears."},"mandates_incomplete":{"type":"boolean","description":"True when mandates in other companies could not all be gathered in time."},"relations":{"type":"object","properties":{"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Officer id or SIREN."},"type":{"type":"string","enum":["officer","company"]},"name":{"type":"string"},"level":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"0: this officer. 1: their companies. 2: the other officers of those companies."}},"required":["id","type","name","level"]}},"links":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","description":"Node id."},"target":{"type":"string","description":"Node id."},"role":{"type":"string","description":"Role, in French."}},"required":["source","target","role"]}}},"required":["nodes","links"],"description":"Relationship graph: companies of the officer and their other officers (bounded)."}},"required":["id","first_names","last_name","usage_name","birth_month","mandates","mandates_incomplete","relations"],"description":"An officer (person) with mandates and relationships."},"NafActivity":{"type":"object","properties":{"code":{"type":"string","description":"Sub-class code. Example: \"10.71C\"."},"label":{"type":"string","description":"Label, in French. Example: \"Boulangerie et boulangerie-pâtisserie\"."},"class":{"type":"string","description":"Class code. Example: \"10.71\"."},"group":{"type":"string","description":"Group code. Example: \"10.7\"."},"division":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"],"description":"Division (2 digits)."},"section":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"],"description":"Section (letter A to U)."},"sector":{"description":"Gabin sector slug, null outside sectors.","type":["string","null"]}},"required":["code","label","class","group","division","section","sector"],"description":"A NAF rev. 2 sub-class (the level SIRENE stores)."},"LegalForm":{"type":"object","properties":{"id":{"type":"string","description":"Value for the `legal_form` filter. Example: \"sas\"."},"label":{"type":"string","description":"Label, in French. Example: \"SAS, SASU\"."}},"required":["id","label"],"description":"A legal form family (groups of INSEE legal categories). Sole proprietorships are not a family."},"HeadcountRange":{"type":"object","properties":{"code":{"type":"string","enum":["11","12","21","22","31","32","41","42","51","52","53","NN","00","01","02","03"],"description":"INSEE code, value for the `headcount` filter. Example: \"11\"."},"label":{"type":"string","description":"Label, in French. Example: \"10 à 19 salariés\"."},"min_employees":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Lower bound, null when not reported."},"max_employees":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Upper bound, null when open-ended or not reported."}},"required":["code","label","min_employees","max_employees"],"description":"An INSEE headcount range."},"Me":{"type":"object","properties":{"account_id":{"type":"string","description":"Id of the Gabin account the credential belongs to."},"credential":{"type":"object","properties":{"type":{"type":"string","enum":["api_key","oauth"],"description":"`api_key`: gab_live_ key. `oauth`: OAuth access token (MCP connectors)."},"id":{"type":"string","description":"Id of the API key, or of the OAuth client."}},"required":["type","id"]},"plan":{"type":"string","enum":["free"],"description":"Plan of the account."},"rate_limit":{"type":"object","properties":{"limit":{"type":"number","description":"Allowance of the window."},"remaining":{"type":"number","description":"Units left in the window (rounded down)."},"reset_seconds":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Seconds until the window resets."}},"required":["limit","remaining","reset_seconds"],"description":"Per-account rate limit: weighted requests per minute (60 on the free plan). A request weighs 1 unless its endpoint says otherwise."},"quota":{"type":"object","properties":{"limit":{"type":"number","description":"Allowance of the window."},"remaining":{"type":"number","description":"Units left in the window (rounded down)."},"reset_seconds":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Seconds until the window resets."}},"required":["limit","remaining","reset_seconds"],"description":"Daily quota (UTC day): weighted units per day (5,000 on the free plan)."},"usage_today":{"anyOf":[{"type":"object","properties":{"requests":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Requests made today (UTC)."},"units":{"type":"number","description":"Units consumed today (UTC)."}},"required":["requests","units"]},{"type":"null"}],"description":"Usage recorded today across all credentials of the account; null when not available yet."}},"required":["account_id","credential","plan","rate_limit","quota","usage_today"],"description":"The account behind the credential, its plan and remaining allowance."},"BuildingSummary":{"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\"."},"gabin_url":{"type":"string","description":"Page of the building on the gabin.ai map."},"address":{"description":"Main address (BAN); null when the building has none.","type":["string","null"]},"insee":{"description":"INSEE code of the city.","type":["string","null"]},"iris":{"description":"IRIS code (INSEE statistical unit) of the building.","type":["string","null"]},"usage":{"anyOf":[{"type":"string","enum":["residential","tertiary","industrial","mixed"]},{"type":"null"}],"description":"Main use (BDNB): residential, tertiary (offices, shops, public facilities), industrial (industry, warehouses), mixed. Null when unknown or for outbuildings and farm buildings."},"construction_year":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Construction year (land files)."},"levels":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Number of levels (land files)."},"housing_units":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Number of dwellings (land files)."},"ground_area_m2":{"description":"Footprint area, in m².","type":["number","null"]},"dpe_class":{"anyOf":[{"type":"string","enum":["A","B","C","D","E","F","G"]},{"type":"null"}],"description":"Energy class (DPE) of the representative housing certificate, A to G. Null when none."},"companies_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Legal entities whose establishment is matched to the building by exact address. Can be lower than the list of GET /v1/buildings/{id}/companies, which also uses position matches and owners."},"center":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}],"items":false,"minItems":2,"maxItems":2,"description":"A point inside the footprint, WGS84 `[lon, lat]`."}},"required":["id","gabin_url","address","insee","iris","usage","construction_year","levels","housing_units","ground_area_m2","dpe_class","companies_count","center"],"description":"A building in a list."},"Building":{"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\"."},"gabin_url":{"type":"string","description":"Page of the building on the gabin.ai map."},"name":{"description":"Name of the place (residence, school, hospital…). Example: \"Résidence l'Orangerie\".","type":["string","null"]},"address":{"type":"string","description":"Main address (BAN). Example: \"40 Rue de Bruxelles, 69100 Villeurbanne\"."},"other_addresses":{"type":"array","items":{"type":"string"},"description":"Other addresses (corner, through building)."},"postal_code":{"description":"Postal code of the main address. Example: \"69100\".","type":["string","null"]},"insee":{"description":"INSEE code of the city. Example: \"69266\".","type":["string","null"]},"city":{"anyOf":[{"type":"object","properties":{"insee":{"type":"string"},"name":{"type":"string"},"department":{"type":"string"}},"required":["insee","name","department"]},{"type":"null"}],"description":"City of the building."},"district":{"anyOf":[{"type":"object","properties":{"iris":{"type":"string"},"name":{"type":"string"}},"required":["iris","name"]},{"type":"null"}],"description":"District (merged IRIS) containing the building's center."},"usage":{"anyOf":[{"type":"string","enum":["residential","tertiary","industrial","mixed"]},{"type":"null"}],"description":"Main use (BDNB): residential, tertiary (offices, shops, public facilities), industrial (industry, warehouses), mixed. Null when unknown or for outbuildings and farm buildings."},"construction_year":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Construction year (land files)."},"levels":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Number of levels (land files)."},"housing_units":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Number of dwellings (land files)."},"ground_area_m2":{"description":"Footprint area, in m².","type":["number","null"]},"dpe_class":{"anyOf":[{"type":"string","enum":["A","B","C","D","E","F","G"]},{"type":"null"}],"description":"Energy class (DPE) of the representative housing certificate, A to G. Null when none."},"height_m":{"description":"Mean height (BD TOPO), in meters.","type":["number","null"]},"heating_energy":{"description":"Heating energy of the representative certificate, in French. Example: \"Gaz\".","type":["string","null"]},"center":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}],"items":false,"minItems":2,"maxItems":2,"description":"A point inside the footprint, WGS84 `[lon, lat]`."},"footprint":{"anyOf":[{"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."},{"type":"null"}],"description":"Footprint (outer ring), GeoJSON Polygon."},"companies_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Companies linked to the building (occupants, sole proprietorships included, and corporate owners), counted up to 1,000. List: GET /v1/buildings/{id}/companies."},"companies_count_capped":{"type":"boolean","description":"True when `companies_count` stopped at 1,000."}},"required":["id","gabin_url","name","address","other_addresses","postal_code","insee","city","district","usage","construction_year","levels","housing_units","ground_area_m2","dpe_class","height_m","heating_energy","center","footprint","companies_count","companies_count_capped"],"description":"A building (BDNB): address, characteristics, footprint, linked companies count."},"BuildingCompany":{"type":"object","properties":{"company":{"$ref":"#/components/schemas/CompanySummary"},"roles":{"type":"array","items":{"type":"string","enum":["occupant","owner"]},"description":"`occupant`: an establishment of the company is located in the building. `owner`: the company owns property in it (land files)."},"establishment":{"anyOf":[{"type":"object","properties":{"siret":{"type":"string","description":"SIRET of the establishment in the building."},"headquarters":{"type":"boolean","description":"True for the registered office."},"trade_name":{"description":"Trade name (enseigne) of the establishment.","type":["string","null"]},"naf_code":{"description":"NAF code of the establishment.","type":["string","null"]},"naf_label":{"type":"string","description":"Label of the NAF code, in French."},"active":{"type":"boolean","description":"False when the establishment is closed."}},"required":["siret","headquarters","trade_name","naf_code","naf_label","active"]},{"type":"null"}],"description":"Establishment through which the company occupies the building; null for an owner only."}},"required":["company","roles","establishment"],"description":"A company linked to a building: a legal entity, or a sole proprietorship occupying it (registered name). Never a company under partial diffusion."},"BuildingEnergy":{"type":"object","properties":{"representative_class":{"anyOf":[{"type":"string","enum":["A","B","C","D","E","F","G"]},{"type":"null"}],"description":"Energy class of the representative certificate (BDNB); the class, A (best) to G."},"class_distribution":{"anyOf":[{"type":"object","properties":{"A":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"B":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"C":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"D":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"E":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"F":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"G":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["A","B","C","D","E","F","G"]},{"type":"null"}],"description":"Number of housing certificates per energy class (BDNB statistics)."},"housing_certificates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ADEME certificate number. Example: \"2369E0123456X\"."},"energy_class":{"anyOf":[{"type":"string","enum":["A","B","C","D","E","F","G"]},{"type":"null"}],"description":"Energy class, A (best) to G."},"ghg_class":{"anyOf":[{"type":"string","enum":["A","B","C","D","E","F","G"]},{"type":"null"}],"description":"Greenhouse gas class, A (best) to G."},"certificate_type":{"description":"Certificate type, in French. Example: \"dpe appartement individuel\".","type":["string","null"]},"issued_on":{"description":"Date the certificate was issued (YYYY-MM-DD).","type":["string","null"]},"construction_year":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Construction year declared."},"area_m2":{"description":"Surface covered by the certificate, in m².","type":["number","null"]},"primary_energy_kwh_m2_year":{"description":"Primary energy use (5 uses), in kWh/m²/year.","type":["number","null"]},"ghg_kg_m2_year":{"description":"Greenhouse gas emissions (5 uses), in kgCO₂/m²/year.","type":["number","null"]},"heating_energy":{"description":"Heating energy, in French.","type":["string","null"]},"address":{"description":"Address carried by the certificate.","type":["string","null"]},"building_type":{"description":"\"appartement\", \"maison\" or \"immeuble\".","type":["string","null"]},"heating_generator":{"description":"Heating generator, in French.","type":["string","null"]},"heating_system":{"description":"Heating installation (individual, collective), in French.","type":["string","null"]},"hot_water_energy":{"description":"Domestic hot water energy, in French.","type":["string","null"]},"ventilation":{"description":"Ventilation, in French.","type":["string","null"]},"wall_insulation":{"description":"Wall insulation, in French.","type":["string","null"]},"glazing":{"description":"Glazing, in French.","type":["string","null"]}},"required":["id","energy_class","ghg_class","certificate_type","issued_on","construction_year","area_m2","primary_energy_kwh_m2_year","ghg_kg_m2_year","heating_energy","address","building_type","heating_generator","heating_system","hot_water_energy","ventilation","wall_insulation","glazing"],"description":"An energy performance certificate (DPE) of a dwelling or a residential building."},"description":"Housing certificates, most recent first, up to 60."},"commercial_certificates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ADEME certificate number. Example: \"2369E0123456X\"."},"energy_class":{"anyOf":[{"type":"string","enum":["A","B","C","D","E","F","G"]},{"type":"null"}],"description":"Energy class, A (best) to G."},"ghg_class":{"anyOf":[{"type":"string","enum":["A","B","C","D","E","F","G"]},{"type":"null"}],"description":"Greenhouse gas class, A (best) to G."},"certificate_type":{"description":"Certificate type, in French. Example: \"dpe appartement individuel\".","type":["string","null"]},"issued_on":{"description":"Date the certificate was issued (YYYY-MM-DD).","type":["string","null"]},"construction_year":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Construction year declared."},"area_m2":{"description":"Surface covered by the certificate, in m².","type":["number","null"]},"primary_energy_kwh_m2_year":{"description":"Primary energy use (5 uses), in kWh/m²/year.","type":["number","null"]},"ghg_kg_m2_year":{"description":"Greenhouse gas emissions (5 uses), in kgCO₂/m²/year.","type":["number","null"]},"heating_energy":{"description":"Heating energy, in French.","type":["string","null"]},"address":{"description":"Address carried by the certificate.","type":["string","null"]},"erp_category":{"description":"Category of establishment open to the public (ERP), when relevant.","type":["string","null"]},"erp_type":{"description":"Type of ERP, when relevant.","type":["string","null"]}},"required":["id","energy_class","ghg_class","certificate_type","issued_on","construction_year","area_m2","primary_energy_kwh_m2_year","ghg_kg_m2_year","heating_energy","address","erp_category","erp_type"],"description":"An energy performance certificate (DPE) of a tertiary building or premises."},"description":"Tertiary certificates, most recent first, up to 60."},"housing_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Housing certificates attached, beyond the list."},"commercial_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Tertiary certificates attached, beyond the list."}},"required":["representative_class","class_distribution","housing_certificates","commercial_certificates","housing_count","commercial_count"],"description":"Energy performance certificates (DPE) attached to the building (BDNB, ADEME)."},"BuildingTransactions":{"type":"object","properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Transactions on the building's parcels since 2014."},"median_price_m2":{"description":"Median price per m² of the listed built sales. In euros; null when not reported.","type":["number","null"]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"DVF mutation id."},"date":{"type":"string","description":"Date of the sale deed (YYYY-MM-DD)."},"nature":{"type":"string","description":"Nature of the mutation, in French. Example: \"Vente\"."},"price":{"type":"number","description":"Price (valeur foncière), in euros."},"address":{"description":"Address of the main lot.","type":["string","null"]},"parcel_id":{"type":"string","description":"Cadastral parcel of the main lot."},"property_type":{"type":"string","description":"Main property type, in French. Example: \"Appartement\"."},"area_m2":{"type":"number","description":"Built area of the main property type, in m²."},"rooms":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Main rooms of the main property type."},"lots_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of lots in the mutation."},"lots":{"type":"array","items":{"type":"object","properties":{"property_type":{"type":"string","description":"Property type, in French."},"area_m2":{"description":"Built area, in m².","type":["number","null"]},"rooms":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Main rooms."},"parcel_id":{"description":"Cadastral parcel.","type":["string","null"]}},"required":["property_type","area_m2","rooms","parcel_id"]},"description":"Built lots of the mutation."},"land":{"type":"array","items":{"type":"object","properties":{"area_m2":{"type":"number","description":"Land area, in m²."},"land_use":{"description":"Land use code (S soils, J gardens, T arable land…). Example: \"S\".","type":["string","null"]},"special_land_use":{"description":"Special land use code.","type":["string","null"]},"parcel_id":{"description":"Cadastral parcel.","type":["string","null"]}},"required":["area_m2","land_use","special_land_use","parcel_id"]},"description":"Land parts of the mutation."},"other_parcels":{"type":"array","items":{"type":"string"},"description":"Other parcels sold in the same mutation."}},"required":["id","date","nature","price","address","parcel_id","property_type","area_m2","rooms","lots_count","lots","land","other_parcels"],"description":"A property transaction (DVF, DGFiP)."},"description":"Transactions, most recent first, up to 100."}},"required":["total","median_price_m2","items"],"description":"Property transactions (DVF) on the building's cadastral parcels since 2014. No party to a sale is named."},"BuildingOwners":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"siren":{"description":"SIREN of the owner; null for a company outside SIRENE or under partial diffusion.","type":["string","null"]},"name":{"type":"string","description":"Name of the owner (SIRENE, else land files)."},"company":{"anyOf":[{"$ref":"#/components/schemas/CompanySummary"},{"type":"null"}],"description":"Company profile when the owner has one."},"units_owned":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Premises of the building owned according to the BDNB (land files)."},"holdings":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["unit","parcel"],"description":"`unit`: premises; `parcel`: the land."},"floor":{"description":"MAJIC level code (\"00\" ground floor, \"91\" cellar).","type":["string","null"]},"entrance":{"description":"Entrance.","type":["string","null"]},"right":{"description":"MAJIC right code (P owner, U usufructuary, N bare owner, G manager…).","type":["string","null"]},"owner_group":{"description":"MAJIC owner group (1 State, 4 city, 7 co-owner…).","type":["string","null"]},"land_use":{"description":"Land use code of a parcel holding.","type":["string","null"]}},"required":["type","floor","entrance","right","owner_group","land_use"]},"description":"Holdings listed in the MAJIC files of legal entities, on the building's parcels."},"property_manager":{"anyOf":[{"type":"object","properties":{"score":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Score of the property-manager signals."},"confidence":{"type":"string","enum":["low","medium","high","confirmed"],"description":"Confidence that this owner is a property manager (régie)."},"signals":{"type":"array","items":{"type":"string"},"description":"Signals found, in French."}},"required":["score","confidence","signals"]},{"type":"null"}],"description":"Present when the owner looks like a property manager rather than an owner."},"likely_owner":{"anyOf":[{"type":"object","properties":{"score":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Score of the signals."},"signals":{"type":"array","items":{"type":"string"},"description":"Signals found, in French."}},"required":["score","signals"]},{"type":"null"}],"description":"Present for an occupant that looks like the owner without a land registry title."},"sources":{"type":"array","items":{"type":"string","enum":["bdnb","majic","sirene"]},"description":"`bdnb` and `majic`: land files; `sirene`: inferred from an occupant."}},"required":["siren","name","company","units_owned","holdings","property_manager","likely_owner","sources"],"description":"An owner of the building (legal entity)."},"description":"Owners, the one holding the most first."},"parcels":{"type":"array","items":{"type":"string"},"description":"Cadastral parcels of the building read in MAJIC."}},"required":["items","parcels"],"description":"Owners of the building: legal entities from the land files (BDNB, MAJIC), then occupants that look like the owner (`likely_owner`), sole proprietorships included under their registered name."},"BuildingCondominium":{"type":"object","properties":{"condominium":{"anyOf":[{"type":"object","properties":{"registration_number":{"type":"string","description":"Number in the national register (RNIC)."},"name":{"description":"Usual name.","type":["string","null"]},"address":{"description":"Address.","type":["string","null"]},"lots":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Total lots."},"housing_lots":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Housing lots."},"parking_lots":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Parking lots."},"construction_period":{"description":"Construction period, in French.","type":["string","null"]},"manager_type":{"description":"Type of manager: \"professionnel\", \"bénévole\", \"coopératif\".","type":["string","null"]},"mandate":{"description":"Current mandate, as declared.","type":["string","null"]},"manager":{"anyOf":[{"type":"object","properties":{"siret":{"type":"string","description":"SIRET of the professional manager (syndic)."},"company":{"$ref":"#/components/schemas/CompanySummary"},"source":{"type":"string","enum":["rnic","bdnb_historique"],"description":"`rnic`: register; `bdnb_historique`: historical BDNB fallback."}},"required":["siret","company","source"]},{"type":"null"}],"description":"Professional manager; null for a volunteer manager (a person, not named) or none."},"volunteer_manager":{"type":"boolean","description":"True when a volunteer manager exists: an individual, never named."}},"required":["registration_number","name","address","lots","housing_lots","parking_lots","construction_period","manager_type","mandate","manager","volunteer_manager"]},{"type":"null"}],"description":"Null when the building is not a registered condominium."}},"required":["condominium"],"description":"Condominium of the building (RNIC register)."},"BuildingParcels":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Cadastral parcel id (14 characters). Example: \"69266000AB0123\"."},"label":{"type":"string","description":"Example: \"Parcelle AB 123\"."},"section":{"description":"Cadastral section.","type":["string","null"]},"number":{"description":"Plan number.","type":["string","null"]},"area_m2":{"description":"Cadastral area, in m².","type":["number","null"]},"main":{"type":"boolean","description":"True for the main parcel of the building."},"geometry":{"anyOf":[{"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."},{"type":"null"}],"description":"Parcel boundary, GeoJSON."}},"required":["id","label","section","number","area_m2","main","geometry"],"description":"A cadastral parcel under the building. Details: GET /v1/parcels/{id}."}}},"required":["items"],"description":"Cadastral parcels of the building."},"BuildingParking":{"type":"object","properties":{"has_parking":{"type":"boolean","description":"True when any source reports parking."},"condominium_parking_lots":{"description":"Parking lots of the main condominium (RNIC).","type":["number","null"]},"bdnb_parking_lots":{"description":"Garage and parking lots (BDNB).","type":["number","null"]},"osm_parkings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"OpenStreetMap id. Example: \"way/1309113373\"."},"name":{"description":"Name.","type":["string","null"]},"capacity":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Capacity."},"type":{"description":"OSM `parking` tag (surface, underground, multi-storey…).","type":["string","null"]},"access":{"description":"OSM `access` tag.","type":["string","null"]},"fee":{"description":"OSM `fee` tag.","type":["string","null"]},"operator":{"description":"Operator.","type":["string","null"]},"area_m2":{"description":"Area, in m².","type":["number","null"]},"match":{"type":"string","enum":["intersects","within_50m"],"description":"`intersects` the building, or `within_50m` of it."},"distance_m":{"description":"Distance to the building, in meters.","type":["number","null"]}},"required":["id","name","capacity","type","access","fee","operator","area_m2","match","distance_m"]},"description":"Parkings mapped in OpenStreetMap."},"ev_charging_stations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"IRVE station id."},"name":{"description":"Name.","type":["string","null"]},"operator":{"description":"Operator.","type":["string","null"]},"owner":{"description":"Owner (aménageur).","type":["string","null"]},"charging_points":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Charging points."},"max_power_kw":{"description":"Maximum power, in kW.","type":["number","null"]},"location_type":{"description":"Location type (implantation), in French.","type":["string","null"]},"distance_m":{"description":"Distance to the building, in meters.","type":["number","null"]}},"required":["id","name","operator","owner","charging_points","max_power_kw","location_type","distance_m"]},"description":"Electric vehicle charging stations nearby (IRVE)."}},"required":["has_parking","condominium_parking_lots","bdnb_parking_lots","osm_parkings","ev_charging_stations"],"description":"Parking of the building: condominium lots, BDNB, OpenStreetMap, EV charging (IRVE)."},"BuildingPermits":{"type":"object","properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Permits on the building's parcels."},"items":{"type":"array","items":{"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."}},"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"],"description":"A building permit (Sitadel)."},"description":"Permits, most recent first, up to 50."}},"required":["total","items"],"description":"Building permits on the building's parcels (Sitadel, SDES)."},"BuildingFiber":{"type":"object","properties":{"status":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["connected","in_progress","planned","undetermined","not_covered"],"description":"Fiber status of the building."},"imb_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Arcep IMB (building access points) matched."},"infrastructure_operators_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Infrastructure operators."},"nearest_imb_distance_m":{"description":"Distance to the nearest IMB, in meters.","type":["number","null"]},"imb_states":{"type":"array","items":{"type":"string"},"description":"Deployment states of the IMBs, in French."}},"required":["status","imb_count","infrastructure_operators_count","nearest_imb_distance_m","imb_states"]},{"type":"null"}]},"imbs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"IMB id."},"code":{"description":"IMB code.","type":["string","null"]},"address":{"description":"Address.","type":["string","null"]},"units":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Premises served."},"state":{"description":"Deployment state, in French. Example: \"deploye\".","type":["string","null"]},"pm_ref":{"description":"Pooling point (PM) reference.","type":["string","null"]},"pm_available_on":{"description":"Date the pooling point became available.","type":["string","null"]},"infrastructure_operator":{"description":"Infrastructure operator.","type":["string","null"]},"offers":{"type":"array","items":{"type":"object","properties":{"technology":{"type":"string","description":"Technology, in French. Example: \"Fibre optique\"."},"operators":{"type":"array","items":{"type":"string"},"description":"Retail operators."}},"required":["technology","operators"]},"description":"Available offers."}},"required":["id","code","address","units","state","pm_ref","pm_available_on","infrastructure_operator","offers"]},"description":"Arcep IMBs of the building."}},"required":["status","imbs"],"description":"Fiber deployment (Arcep)."},"BuildingPlanning":{"type":"object","properties":{"plu":{"anyOf":[{"type":"object","properties":{"document_type":{"description":"PLU, PLUi, POS, CC or PSMV.","type":["string","null"]},"label":{"description":"Zone label. Example: \"UA1\".","type":["string","null"]},"long_label":{"description":"Long label, in French.","type":["string","null"]},"zone_type":{"description":"U (urban), AU (to urbanize), A (agricultural), N (natural)…","type":["string","null"]},"main_use":{"description":"Dominant use, in French.","type":["string","null"]},"approved_on":{"description":"Approval date of the document.","type":["string","null"]},"document_title":{"description":"Title of the document.","type":["string","null"]},"regulation_url":{"description":"URL of the zone regulation.","type":["string","null"]},"gpu_url":{"description":"Page of the document on the Géoportail de l'Urbanisme.","type":["string","null"]}},"required":["document_type","label","long_label","zone_type","main_use","approved_on","document_title","regulation_url","gpu_url"]},{"type":"null"}],"description":"Local urban plan zone (PLU, PLUi, POS, CC)."},"psmv":{"anyOf":[{"type":"object","properties":{"document_type":{"description":"PLU, PLUi, POS, CC or PSMV.","type":["string","null"]},"label":{"description":"Zone label. Example: \"UA1\".","type":["string","null"]},"long_label":{"description":"Long label, in French.","type":["string","null"]},"zone_type":{"description":"U (urban), AU (to urbanize), A (agricultural), N (natural)…","type":["string","null"]},"main_use":{"description":"Dominant use, in French.","type":["string","null"]},"approved_on":{"description":"Approval date of the document.","type":["string","null"]},"document_title":{"description":"Title of the document.","type":["string","null"]},"regulation_url":{"description":"URL of the zone regulation.","type":["string","null"]},"gpu_url":{"description":"Page of the document on the Géoportail de l'Urbanisme.","type":["string","null"]}},"required":["document_type","label","long_label","zone_type","main_use","approved_on","document_title","regulation_url","gpu_url"]},{"type":"null"}],"description":"Safeguard plan zone (PSMV), in a remarkable heritage site."},"heritage":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["monument","abords","spr","site"],"description":"`monument` historic monument, `abords` its surroundings, `spr` remarkable heritage site, `site` listed site."},"id":{"type":"string","description":"Id of the protection."},"name":{"description":"Name.","type":["string","null"]},"surroundings_mode":{"anyOf":[{"type":"string","enum":["radius","pda"]},{"type":"null"}],"description":"Surroundings: 500 m `radius` or delimited perimeter `pda`."},"distance_m":{"description":"Distance from the building, in meters; 0 inside.","type":["number","null"]},"description":{"description":"Description, in French.","type":["string","null"]},"updated_on":{"description":"Last update.","type":["string","null"]}},"required":["type","id","name","surroundings_mode","distance_m","description","updated_on"]},"description":"Heritage easements (approval of the Architecte des Bâtiments de France)."},"monument":{"description":"Name of the monument when the building itself is protected.","type":["string","null"]}},"required":["plu","psmv","heritage","monument"],"description":"Urban planning of the building: PLU zone, PSMV, heritage easements."},"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."},"CompanyBuilding":{"type":"object","properties":{"building":{"$ref":"#/components/schemas/BuildingSummary"},"roles":{"type":"array","items":{"type":"string","enum":["occupant","owner"]},"description":"`occupant`: an establishment of the company is matched to the building. `owner`: the company owns property in it (land files, BDNB)."},"establishments":{"type":"array","items":{"type":"string"},"description":"SIRET of the company's establishments matched to the building (occupant)."},"active_establishments":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many of `establishments` are open."},"units_owned":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Premises owned in the building according to the BDNB (owner); null when unknown."}},"required":["building","roles","establishments","active_establishments","units_owned"],"description":"A building occupied and/or owned by a company."},"Parcel":{"type":"object","properties":{"id":{"type":"string","description":"Cadastral parcel id."},"label":{"type":"string","description":"Example: \"Parcelle AB 123\"."},"insee":{"description":"INSEE code of the city.","type":["string","null"]},"prefix":{"description":"Section prefix (former city), null when 000.","type":["string","null"]},"section":{"description":"Cadastral section. Example: \"AB\".","type":["string","null"]},"number":{"description":"Plan number, 4 digits. Example: \"0123\".","type":["string","null"]},"area_m2":{"description":"Cadastral area, in m².","type":["number","null"]},"center":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}],"items":false,"minItems":2,"maxItems":2,"description":"WGS84 coordinates `[lon, lat]`. Example: [4.8795, 45.7665]."},"geometry":{"anyOf":[{"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."},{"type":"null"}],"description":"Parcel boundary, GeoJSON."},"city":{"anyOf":[{"type":"object","properties":{"insee":{"type":"string"},"name":{"type":"string"},"department":{"type":"string"}},"required":["insee","name","department"]},{"type":"null"}],"description":"City of the parcel."},"district":{"anyOf":[{"type":"object","properties":{"iris":{"type":"string"},"name":{"type":"string"}},"required":["iris","name"]},{"type":"null"}],"description":"District containing the parcel's center."},"buildings":{"type":"array","items":{"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"]},"description":"Buildings on the parcel, up to 20."},"gabin_url":{"type":"string","description":"Page of the parcel on the gabin.ai map."}},"required":["id","label","insee","prefix","section","number","area_m2","center","geometry","city","district","buildings","gabin_url"],"description":"A cadastral parcel (BDNB): boundary, area, buildings. Owners are not listed."},"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)."},"Place":{"type":"object","properties":{"name":{"type":"string","description":"Name of the place. Example: \"Résidence l'Orangerie\"."},"category":{"description":"Category: residence, sante, enseignement, ehpad, hotel, commerce…; null if unknown.","type":["string","null"]},"building_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\"."},"city":{"description":"City.","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":"Center of the building."}},"required":["name","category","building_id","city","location"],"description":"A named place (residence, hospital, school…) and its building."},"City":{"type":"object","properties":{"insee":{"type":"string","description":"INSEE code."},"name":{"type":"string","description":"Name. Example: \"Villeurbanne\"."},"department":{"type":"string","description":"Department code. Example: \"69\"."},"postal_code":{"type":"string","description":"Main postal code."},"population":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Population (INSEE)."},"center":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}],"items":false,"minItems":2,"maxItems":2,"description":"WGS84 coordinates `[lon, lat]`. Example: [4.8795, 45.7665]."}},"required":["insee","name","department","postal_code","population","center"],"description":"A city or an arrondissement of Paris, Lyon or Marseille."},"District":{"type":"object","properties":{"iris":{"type":"string","description":"IRIS code of the district (its first IRIS when merged)."},"name":{"type":"string","description":"Readable name. Example: \"Gratte-Ciel\"."},"insee":{"type":"string","description":"INSEE code of its city."}},"required":["iris","name","insee"],"description":"A district: one or several merged IRIS with a readable name."},"DepartmentCity":{"type":"object","properties":{"insee":{"type":"string","description":"INSEE code."},"name":{"type":"string","description":"Name."},"postal_code":{"type":"string","description":"Main postal code."},"population":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Population (INSEE)."},"arrondissement":{"type":"boolean","description":"True for an arrondissement of Paris, Lyon or Marseille, listed next to its city."}},"required":["insee","name","postal_code","population","arrondissement"],"description":"A city of a department."},"ZoneMarket":{"type":"object","properties":{"level":{"type":"string","enum":["region","department","city","district"],"description":"Level of the requested zone."},"code":{"type":"string","description":"Code of the requested zone."},"name":{"type":"string","description":"Name of the requested zone."},"parents":{"type":"object","properties":{"city":{"anyOf":[{"type":"object","properties":{"insee":{"type":"string"},"name":{"type":["string","null"]}},"required":["insee","name"]},{"type":"null"}]},"district":{"anyOf":[{"type":"object","properties":{"iris":{"type":"string"},"name":{"type":["string","null"]}},"required":["iris","name"]},{"type":"null"}]},"department":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"name":{"type":["string","null"]}},"required":["code","name"]},{"type":"null"}]},"region":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"name":{"type":["string","null"]}},"required":["code","name"]},{"type":"null"}]}},"required":["city","district","department","region"],"description":"Zones containing the requested one."},"prices":{"type":"array","items":{"type":"object","properties":{"level":{"type":"string","enum":["region","department","city","district"],"description":"Level of this zone."},"code":{"type":"string","description":"Code of this zone."},"name":{"type":"string","description":"Name of this zone."},"series":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Year."},"month":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Month (1 to 12), or 0 for the whole year."},"segment":{"type":"string","description":"Segment: appartement, maison, residentiel (both), terrain, local (commercial)."},"window_years":{"description":"Years pooled to compute the figure.","type":["number","null"]},"median_m2":{"description":"Median price, in euros per m².","type":["number","null"]},"p25_m2":{"description":"First quartile, in euros per m².","type":["number","null"]},"p75_m2":{"description":"Third quartile, in euros per m².","type":["number","null"]},"sales":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Sales retained."},"reliability":{"description":"Reliability flag, in French.","type":["string","null"]}},"required":["year","month","segment","window_years","median_m2","p25_m2","p75_m2","sales","reliability"]},"description":"Sale prices (DVF), one entry per year (and segment)."}},"required":["level","code","name","series"],"description":"Sale prices (DVF) of one zone containing the requested one."}},"top_streets":{"type":"array","items":{"type":"object","properties":{"street":{"type":"string","description":"Street name."},"median_m2":{"type":"number","description":"Median residential price, in euros per m²."},"sales":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Sales retained."},"year":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Year."}},"required":["street","median_m2","sales","year"]},"description":"Most active streets of the city, by median price (DVF)."},"rents":{"type":"array","items":{"type":"object","properties":{"level":{"type":"string","enum":["region","department","city","district"],"description":"Level of this zone."},"code":{"type":"string","description":"Code of this zone."},"name":{"type":"string","description":"Name of this zone."},"series":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Year."},"property_type":{"type":"string","description":"appart, appart_t1t2, appart_t3plus or maison."},"reference_area_m2":{"description":"Reference area of the estimate, in m².","type":["number","null"]},"rent_m2":{"description":"Estimated rent, in euros per m² per month (charges included).","type":["number","null"]},"rent_m2_low":{"description":"Lower bound of the prediction interval.","type":["number","null"]},"rent_m2_high":{"description":"Upper bound of the prediction interval.","type":["number","null"]},"model_level":{"description":"Level of the estimate (commune, epci, maille…).","type":["string","null"]}},"required":["year","property_type","reference_area_m2","rent_m2","rent_m2_low","rent_m2_high","model_level"]},"description":"Rents (ANIL), one entry per year (and segment)."}},"required":["level","code","name","series"],"description":"Rents (ANIL) of one zone containing the requested one."}},"demography":{"type":"array","items":{"type":"object","properties":{"level":{"type":"string","enum":["region","department","city","district"],"description":"Level of this zone."},"code":{"type":"string","description":"Code of this zone."},"name":{"type":"string","description":"Name of this zone."},"series":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Census year."},"population":{"description":"Total population.","type":["number","null"]},"age_0_10":{"description":"Population aged 0 to 10.","type":["number","null"]},"age_11_17":{"description":"Population aged 11 to 17.","type":["number","null"]},"age_18_24":{"description":"Population aged 18 to 24.","type":["number","null"]},"age_25_39":{"description":"Population aged 25 to 39.","type":["number","null"]},"age_40_54":{"description":"Population aged 40 to 54.","type":["number","null"]},"age_55_64":{"description":"Population aged 55 to 64.","type":["number","null"]},"age_65_79":{"description":"Population aged 65 to 79.","type":["number","null"]},"age_80_plus":{"description":"Population aged 80 and over.","type":["number","null"]},"foreigners":{"description":"Population of foreign nationality.","type":["number","null"]},"households_population":{"description":"Population living in ordinary households.","type":["number","null"]},"aged_15_plus":{"description":"Population aged 15 and over (base of the occupations).","type":["number","null"]},"farmers":{"description":"Population aged 15+: farmers.","type":["number","null"]},"craftsmen_merchants":{"description":"Population aged 15+: craftsmen, merchants, business owners.","type":["number","null"]},"managers":{"description":"Population aged 15+: managers, higher intellectual professions.","type":["number","null"]},"intermediate_professions":{"description":"Population aged 15+: intermediate professions.","type":["number","null"]},"employees":{"description":"Population aged 15+: employees.","type":["number","null"]},"workers":{"description":"Population aged 15+: blue-collar workers.","type":["number","null"]},"retirees":{"description":"Population aged 15+: retirees.","type":["number","null"]},"inactive":{"description":"Population aged 15+: other inactive.","type":["number","null"]}},"required":["year","population","age_0_10","age_11_17","age_18_24","age_25_39","age_40_54","age_55_64","age_65_79","age_80_plus","foreigners","households_population","aged_15_plus","farmers","craftsmen_merchants","managers","intermediate_professions","employees","workers","retirees","inactive"]},"description":"Population (INSEE census), one entry per year (and segment)."}},"required":["level","code","name","series"],"description":"Population (INSEE census) of one zone containing the requested one."}},"income":{"type":"array","items":{"type":"object","properties":{"level":{"type":"string","enum":["region","department","city","district"],"description":"Level of this zone."},"code":{"type":"string","description":"Code of this zone."},"name":{"type":"string","description":"Name of this zone."},"series":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Year."},"median_declared":{"description":"Median declared income per consumption unit, euros per year.","type":["number","null"]},"median_disposable":{"description":"Median disposable income per consumption unit, euros per year.","type":["number","null"]},"disposable_q1":{"description":"First quartile of disposable income.","type":["number","null"]},"disposable_q3":{"description":"Third quartile of disposable income.","type":["number","null"]},"poverty_rate_pct":{"description":"Poverty rate (60% threshold), in percent.","type":["number","null"]},"taxable_households_pct":{"description":"Share of taxable households, in percent.","type":["number","null"]},"gini":{"description":"Gini index of disposable income.","type":["number","null"]},"interdecile_ratio":{"description":"Interdecile ratio D9/D1.","type":["number","null"]},"activity_income_pct":{"description":"Share of activity income, in percent.","type":["number","null"]},"wages_pct":{"description":"Share of wages, in percent.","type":["number","null"]},"pensions_pct":{"description":"Share of pensions, in percent.","type":["number","null"]},"social_benefits_pct":{"description":"Share of social benefits, in percent.","type":["number","null"]},"taxes_pct":{"description":"Share of taxes (negative), in percent.","type":["number","null"]}},"required":["year","median_declared","median_disposable","disposable_q1","disposable_q3","poverty_rate_pct","taxable_households_pct","gini","interdecile_ratio","activity_income_pct","wages_pct","pensions_pct","social_benefits_pct","taxes_pct"]},"description":"Income (INSEE FiLoSoFi), one entry per year (and segment)."}},"required":["level","code","name","series"],"description":"Income (INSEE FiLoSoFi) of one zone containing the requested one."}}},"required":["level","code","name","parents","prices","top_streets","rents","demography","income"],"description":"Market and territory figures of a zone, at every level containing it (district, city, department, region)."},"SearchField":{"type":"object","properties":{"id":{"type":"string","description":"Field id to use in a condition. Example: \"batiment.annee_construction\"."},"target":{"type":"string","enum":["buildings","companies"],"description":"Target the field applies to."},"object":{"type":"string","description":"Object the field describes: batiment, dpe, copro, proprietaire, occupant, entreprise."},"label":{"type":"string","description":"Label, in French."},"description":{"type":"string","description":"What the data means and its limits, in French."},"type":{"type":"string","enum":["enum","naf","number","boolean","text"],"description":"Type of the field; it sets which condition keys apply."},"operator":{"type":"string","enum":["in","in_naf","between","is","starts_with"],"description":"`in`: `values` from `values` below (any of them). `in_naf`: NAF codes (sub-class 49.41A, class 49.41, division 49). `between`: `min` and/or `max`, inclusive. `is`: `values: [\"true\"]` or `[\"false\"]`. `starts_with`: `values: [prefix]`."},"unit":{"description":"Unit of a number field, in French.","type":["string","null"]},"values":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"]}},{"type":"null"}],"description":"Accepted codes of an `enum` field, with their French label."},"source":{"type":"string","description":"Table and column read (BDNB schema abbreviated `bdnb`)."}},"required":["id","target","object","label","description","type","operator","unit","values","source"],"description":"A filterable field of the multi-criteria search."},"SearchFilters":{"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"]}}},"required":["target","conditions","any_of"]},"SearchCount":{"type":"object","properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Matching results, counted up to 100,000."},"total_kind":{"type":"string","enum":["exact","lower_bound"],"description":"`lower_bound`: at least `total` (counting stopped at 100,000)."},"breakdowns":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","description":"Field or dimension of the breakdown."},"label":{"type":"string","description":"Label, in French."},"rows":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string","description":"Value code."},"label":{"type":"string","description":"Value label, in French."},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Results with this value."}},"required":["value","label","count"]}}},"required":["field","label","rows"]}},{"type":"null"}],"description":"Breakdowns of the results (use, energy class, city…); null when they took too long."}},"required":["total","total_kind","breakdowns"],"description":"Count of a multi-criteria search."},"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`)."}}}}