{"openapi":"3.1.0","info":{"title":"AXITAM Public API","description":"Reference data (ISO, CLDR), Belgian enterprises, annual accounts and addresses, Peppol participants - built on community-maintained and official sources. See the data-sources API for each source's version and license. Beta.","version":"0.10.0"},"servers":[{"url":"/","description":"This server"}],"tags":[{"name":"Belgian addresses","description":"Autocompletion of a Belgian address in three guided steps - municipality, street, house number - then the full address with its official BeSt identifier and its WGS84 position. Source: BeSt Address, the federal and regional address registers (BOSA, Brussels, Flanders, Wallonia), queried live; data licensed CC BY 4.0 by BOSA and the three regions, attribution required. Identifiers are the regional URIs BeSt publishes: pass them back exactly as received."}],"paths":{"/api/v1/bel/addresses":{"get":{"tags":["Belgian addresses"],"summary":"Read one address","description":"The full address behind a BeSt identifier, as returned by the house-number step: street, house and box numbers, postal code, municipality, WGS84 position and register status. The identifier is a query parameter because the regional URIs contain slashes and colons.","operationId":"findAddress","parameters":[{"name":"id","in":"query","description":"BeSt identifier of the address, exactly as received","required":true,"schema":{"type":"string","maxLength":300,"minLength":0,"pattern":"^\\S+$"},"example":"https://databrussels.be/id/address/210225/1"}],"responses":{"200":{"description":"Address found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/BelgianAddressResponse"}}}},"400":{"description":"id missing or with a space (code INVALID_REQUEST)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"BeSt knows no address with this identifier, or no longer this version of it (code ADDRESS_NOT_FOUND)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"BeSt Address did not answer, or answered an error or an unexpected document (code UPSTREAM_UNAVAILABLE)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Too many requests towards BeSt Address are in flight, retry later (code UPSTREAM_BUSY)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The X-API-Key header carries an unknown, revoked or malformed key (code INVALID_API_KEY). Leave the header out to call anonymously.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests from this client: the code is RATE_LIMITED, Retry-After says in how many seconds a request will pass again.","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Sustained requests per second allowed on this path","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current burst","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{},{"apiKey":[]}]}},"/api/v1/bel/addresses/streets":{"get":{"tags":["Belgian addresses"],"summary":"Autocomplete a street","description":"In one municipality, given by its postal code or by its NIS code (exactly one of the two), by a part of the street name in any language (case, accents, spaces, apostrophes and hyphens ignored). Streets whose name starts with the text come first, then the other matches, alphabetically. Only current street names are returned.","operationId":"findStreets","parameters":[{"name":"postCode","in":"query","description":"Postal code of the municipality (alternative to nisCode)","required":false,"schema":{"type":"string","pattern":"^[0-9]{4}$"},"example":1000},{"name":"nisCode","in":"query","description":"NIS code of the municipality (alternative to postCode)","required":false,"schema":{"type":"string","pattern":"^[0-9]{5}$"},"example":21004},{"name":"name","in":"query","description":"Part of the street name, at least 2 characters","required":true,"schema":{"type":"string","pattern":"^[\\p{L}0-9 '\\-.]{2,100}$"},"example":"loi"},{"name":"limit","in":"query","description":"Maximum number of streets returned","required":false,"schema":{"type":"integer","format":"int32","default":10,"maximum":50,"minimum":1},"example":10}],"responses":{"200":{"description":"Matching streets, possibly none","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StreetResponse"}}}}},"400":{"description":"postCode not 4 digits, nisCode not 5 digits, name shorter than 2 characters or with a forbidden character (wildcards included), or limit out of 1-50 (code INVALID_REQUEST); both or none of postCode and nisCode (code INVALID_ARGUMENT)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"BeSt Address did not answer, or answered an error or an unexpected document (code UPSTREAM_UNAVAILABLE)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Too many requests towards BeSt Address are in flight, retry later (code UPSTREAM_BUSY)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The X-API-Key header carries an unknown, revoked or malformed key (code INVALID_API_KEY). Leave the header out to call anonymously.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests from this client: the code is RATE_LIMITED, Retry-After says in how many seconds a request will pass again.","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Sustained requests per second allowed on this path","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current burst","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{},{"apiKey":[]}]}},"/api/v1/bel/addresses/municipalities":{"get":{"tags":["Belgian addresses"],"summary":"Autocomplete a municipality","description":"By a postal code or the beginning of one (digits only), or by a part of the municipality name in any language (case, accents, spaces, apostrophes and hyphens ignored). Municipalities whose name starts with the text come first, then the other matches, alphabetically; each municipality once, whatever its number of postal codes.","operationId":"findMunicipalities","parameters":[{"name":"q","in":"query","description":"Postal code (or its first digits) or a part of the municipality name","required":true,"schema":{"type":"string","pattern":"^([0-9]{1,4}|[\\p{L}0-9 '\\-.]{2,100})$"},"example":"brux"},{"name":"limit","in":"query","description":"Maximum number of municipalities returned","required":false,"schema":{"type":"integer","format":"int32","default":10,"maximum":50,"minimum":1},"example":10}],"responses":{"200":{"description":"Matching municipalities, possibly none","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MunicipalityResponse"}}}}},"400":{"description":"q shorter than 2 characters (1 for a postal-code prefix), longer than 100, with a character outside letters, digits, spaces, apostrophes, hyphens and dots (wildcards included), or limit out of 1-50 (code INVALID_REQUEST)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"BeSt Address did not answer, or answered an error or an unexpected document (code UPSTREAM_UNAVAILABLE)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Too many requests towards BeSt Address are in flight, retry later (code UPSTREAM_BUSY)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The X-API-Key header carries an unknown, revoked or malformed key (code INVALID_API_KEY). Leave the header out to call anonymously.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests from this client: the code is RATE_LIMITED, Retry-After says in how many seconds a request will pass again.","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Sustained requests per second allowed on this path","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current burst","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{},{"apiKey":[]}]}},"/api/v1/bel/addresses/house-numbers":{"get":{"tags":["Belgian addresses"],"summary":"Autocomplete a house number","description":"Every current address of a street (houses and boxes) or those whose house number starts with the digits typed, in natural order (1, 1A, 2, 10), each house before its boxes.","operationId":"findHouseNumbers","parameters":[{"name":"streetId","in":"query","description":"BeSt identifier of the street, as returned by the street step","required":true,"schema":{"type":"string","maxLength":300,"minLength":0,"pattern":"^\\S+$"},"example":"https://databrussels.be/id/streetname/1679/1"},{"name":"houseNumber","in":"query","description":"Beginning of the house number; omitted, every address of the street","required":false,"schema":{"type":"string","pattern":"^[\\p{L}0-9\\-]{1,10}$"},"example":1},{"name":"limit","in":"query","description":"Maximum number of addresses returned","required":false,"schema":{"type":"integer","format":"int32","default":20,"maximum":100,"minimum":1},"example":20}],"responses":{"200":{"description":"Matching addresses, possibly none","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/HouseNumberResponse"}}}}},"400":{"description":"streetId missing or with a space, houseNumber not 1-10 letters, digits or hyphens, or limit out of 1-100 (code INVALID_REQUEST)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"BeSt Address did not answer, or answered an error or an unexpected document (code UPSTREAM_UNAVAILABLE)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Too many requests towards BeSt Address are in flight, retry later (code UPSTREAM_BUSY)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The X-API-Key header carries an unknown, revoked or malformed key (code INVALID_API_KEY). Leave the header out to call anonymously.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests from this client: the code is RATE_LIMITED, Retry-After says in how many seconds a request will pass again.","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Sustained requests per second allowed on this path","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current burst","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{},{"apiKey":[]}]}}},"components":{"schemas":{"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"correlationId":{"type":"string"}}},"BelgianAddressResponse":{"type":"object","description":"A Belgian address as the BeSt Address registers publish it","properties":{"addressId":{"type":"string","description":"BeSt identifier of the address (a regional URI, versioned: a new version of the address gets a new identifier and the old one answers 404)","example":"https://databrussels.be/id/address/210225/1"},"street":{"$ref":"#/components/schemas/StreetResponse","description":"Street name (its municipality is the one below)"},"houseNumber":{"type":"string","description":"House number, possibly with a letter","example":"16"},"boxNumber":{"type":["string","null"],"description":"Box number, null for the house itself"},"postCode":{"type":"string","description":"Postal code","example":"1000"},"municipality":{"$ref":"#/components/schemas/MunicipalityResponse","description":"Municipality"},"position":{"type":"null","$ref":"#/components/schemas/GeoPositionResponse","description":"WGS84 position, null when the register publishes none (about 120 000 Walloon addresses)"},"status":{"type":"string","description":"Status in the register","example":"current"},"isOfficiallyAssigned":{"type":["boolean","null"],"description":"Whether the address was officially assigned by the municipality, null when the register does not say","example":true}}},"GeoPositionResponse":{"type":"object","description":"WGS84 position in decimal degrees","properties":{"latitude":{"type":"number","description":"Latitude (north)","example":50.846169319921074},"longitude":{"type":"number","description":"Longitude (east)","example":4.366537635141211}}},"LocalizedNameResponse":{"type":"object","description":"A name in the languages the regional register provides (Brussels: nl and fr, Flanders: nl, Wallonia: fr, the German-speaking municipalities: fr, de and nl); an absent language is null","properties":{"nl":{"type":["string","null"],"description":"Dutch name","example":"Wetstraat"},"fr":{"type":["string","null"],"description":"French name","example":"Rue de la Loi"},"de":{"type":["string","null"],"description":"German name"}}},"MunicipalityResponse":{"type":"object","description":"A Belgian municipality as the BeSt Address registers publish it","properties":{"municipalityId":{"type":"string","description":"BeSt identifier of the municipality (a regional URI, to pass back as is)","example":"https://databrussels.be/id/municipality/21004/7"},"nisCode":{"type":"string","description":"NIS code of the municipality","example":"21004"},"name":{"$ref":"#/components/schemas/LocalizedNameResponse","description":"Name of the municipality"}}},"StreetResponse":{"type":"object","description":"A street name as the BeSt Address registers publish it","properties":{"streetId":{"type":"string","description":"BeSt identifier of the street (a regional URI, to pass back as is to the house-number step)","example":"https://databrussels.be/id/streetname/1679/1"},"name":{"$ref":"#/components/schemas/LocalizedNameResponse","description":"Name of the street"},"municipality":{"type":"null","$ref":"#/components/schemas/MunicipalityResponse","description":"Municipality assigning the name; null inside an address, whose municipality is given at address level"}}},"HouseNumberResponse":{"type":"object","description":"One address of a street: a house, or a box of a house","properties":{"addressId":{"type":"string","description":"BeSt identifier of the address (a regional URI, to pass back as is to read the full address)","example":"https://databrussels.be/id/address/210225/1"},"houseNumber":{"type":"string","description":"House number, possibly with a letter","example":"16"},"boxNumber":{"type":["string","null"],"description":"Box number, null for the house itself","example":"b003"}}}},"securitySchemes":{"apiKey":{"type":"apiKey","description":"Optional. A key of a registered developer (portal: /account/) raises the request rate of the client from the anonymous per-IP limit to the plan's. Without it the request is anonymous; an unknown or revoked key is refused (401 INVALID_API_KEY).","name":"X-API-Key","in":"header"}}}}