{"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":"Address search","description":"Free-text search of places and addresses worldwide, as the user types: houses, streets, localities, cities... with their WGS84 position, optionally biased towards a point or restricted to a country. Source: OpenStreetMap data (© OpenStreetMap contributors, ODbL) served by Photon (Komoot), queried live. A Belgian house result carries the best field (its match in the official BeSt Address registers) when the Belgian address composition module is present."}],"paths":{"/api/v1/addresses/search":{"get":{"tags":["Address search"],"summary":"Search places and addresses worldwide","description":"Free text as typed by a user (a street and a number, a city, a landmark...). The results come best first; lat and lon bias them towards a point (both or none), countryCode restricts them to a country. Names come in the language asked when the Photon instance was built with it (the public instance: de, en, fr), otherwise in the instance's default names - the language field of the answer says which. Each result carries its Photon type (house, street, city...) and the fields added by the modules deployed alongside (best: the BeSt Address match of a Belgian house, with a status saying whether the match succeeded).","operationId":"search","parameters":[{"name":"q","in":"query","description":"Text searched, at least 3 characters","required":true,"schema":{"type":"string","pattern":"^[\\p{L}\\p{N}\\s'’.,\\-/()&#°]{3,200}$"},"example":"rue de la loi 16 bruxelles"},{"name":"lat","in":"query","description":"Latitude of the point to bias the results towards (with lon)","required":false,"schema":{"type":"number","maximum":90.0,"minimum":-90.0},"example":50.85},{"name":"lon","in":"query","description":"Longitude of the point to bias the results towards (with lat)","required":false,"schema":{"type":"number","maximum":180.0,"minimum":-180.0},"example":4.35},{"name":"countryCode","in":"query","description":"ISO 3166-1 alpha-2 code of the only country to search in","required":false,"schema":{"type":"string","pattern":"^[A-Z]{2}$"},"example":"BE"},{"name":"lang","in":"query","description":"Language of the names (ISO 639-1), applied when the instance knows it","required":false,"schema":{"type":"string","pattern":"^[a-z]{2}$"},"example":"fr"},{"name":"limit","in":"query","description":"Maximum number of results returned","required":false,"schema":{"type":"integer","format":"int32","default":5,"maximum":20,"minimum":1},"example":5}],"responses":{"200":{"description":"Matching places and addresses, possibly none","content":{"*/*":{"schema":{"$ref":"#/components/schemas/AddressSearchResponse"}}}},"400":{"description":"q shorter than 3 characters, longer than 200 or with a control character, lat or lon out of range, countryCode not two upper-case letters, lang not two lower-case letters or limit out of 1-20 (code INVALID_REQUEST); lat without lon or lon without lat (code INVALID_ARGUMENT)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Photon did not answer, or answered an error or an unexpected document (code UPSTREAM_UNAVAILABLE)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Photon answered 429 or too many requests towards it 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"}}},"AddressSearchResponse":{"type":"object","description":"The places and addresses matching a free-text search","properties":{"query":{"type":"string","description":"The text searched, trimmed","example":"rue de la loi 16"},"language":{"type":["string","null"],"description":"Language applied to the names, null when the instance served its default names because the language asked is not one it was built with","example":"fr"},"results":{"type":"array","description":"Results, best first, possibly none","items":{"$ref":"#/components/schemas/AddressSearchResultResponse"}}}},"AddressSearchResultResponse":{"type":"object","description":"One place or address found, as OpenStreetMap publishes it through Photon; every field but label, type, position and osm may be absent","properties":{"label":{"type":"string","description":"Display line composed by this API from the fields present (the only composed value): name, street and house number, postal code and city, country","example":"Rue de la Loi 16, 1000 Bruxelles, Belgique"},"type":{"type":"string","description":"Kind of place: house, street, locality, district, city, county, state, country or other","example":"house"},"name":{"type":["string","null"],"description":"Name of the place","example":"Sherlock Holmes Museum"},"street":{"type":["string","null"],"description":"Street","example":"Rue de la Loi"},"houseNumber":{"type":["string","null"],"description":"House number","example":"16"},"postCode":{"type":["string","null"],"description":"Postal code","example":"1000"},"city":{"type":["string","null"],"description":"City","example":"Bruxelles"},"district":{"type":["string","null"],"description":"District","example":"Pentagone"},"county":{"type":["string","null"],"description":"County","example":"Bruxelles-Capitale"},"state":{"type":["string","null"],"description":"State or region","example":"Bruxelles-Capitale"},"country":{"type":["string","null"],"description":"Country name in the language served","example":"Belgique"},"countryCode":{"type":["string","null"],"description":"ISO 3166-1 alpha-2 country code","example":"BE"},"position":{"$ref":"#/components/schemas/GeoPointResponse","description":"WGS84 position"},"osm":{"$ref":"#/components/schemas/OsmReferenceResponse","description":"OpenStreetMap object"},"extensions":{"type":["object","null"],"additionalProperties":{},"description":"Fields added by the modules deployed alongside, serialized at the result's top level: best (the BeSt Address match of a Belgian house, when the Belgian address composition module is present)"}}},"GeoPointResponse":{"type":"object","description":"WGS84 position in decimal degrees","properties":{"latitude":{"type":"number","description":"Latitude (north)","example":50.8461212},"longitude":{"type":"number","description":"Longitude (east)","example":4.3663795}}},"OsmReferenceResponse":{"type":"object","description":"The OpenStreetMap object behind the result","properties":{"type":{"type":"string","description":"N (node), W (way) or R (relation)","example":"N"},"id":{"type":"integer","format":"int64","description":"OSM identifier of the object","example":11015484234},"key":{"type":["string","null"],"description":"OSM tag key the result was selected by","example":"place"},"value":{"type":["string","null"],"description":"OSM tag value","example":"house"}}}},"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"}}}}