Places
Lister et rechercher des lieux, puis en lire le détail.
Rechercher des lieux
GET/v1/places/search
Cherche dans tous les noms d’un lieu. near départage seulement les résultats de même qualité.
- Accès requis
places:read- Réponse
application/geo+json
Exemples
cURL
curl --get "$ATLAS_API_URL/v1/places/search" \
--header "Authorization: Bearer $ATLAS_API_KEY" \
--data-urlencode 'q=pharmacie' \
--data-urlencode 'lang=fr' \
--data-urlencode 'near=-15.9785,18.0858' \
--data-urlencode 'limit=5'Node.js
const url = new URL("/v1/places/search", process.env.ATLAS_API_URL);
url.search = new URLSearchParams({
q: "pharmacie",
lang: "fr",
near: "-15.9785,18.0858",
limit: "5",
}).toString();
const response = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.ATLAS_API_KEY}` },
});
const body = await response.json();
if (!response.ok) throw new Error(`ATLASMR ${response.status} ${body.code}`);
console.log(body.meta.status, body.features.length);PHP
<?php
$url = getenv('ATLAS_API_URL') . '/v1/places/search?' . http_build_query([
'q' => 'pharmacie',
'lang' => 'fr',
'near' => '-15.9785,18.0858',
'limit' => '5',
], '', '&', PHP_QUERY_RFC3986);
$curl = curl_init($url);
curl_setopt_array($curl, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ATLAS_API_KEY')],
]);
$body = json_decode(curl_exec($curl), true, 512, JSON_THROW_ON_ERROR);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
if ($status !== 200) {
throw new RuntimeException("ATLASMR {$status} {$body['code']}");
}
echo $body['meta']['status'], ' ', count($body['features']), PHP_EOL;Les exemples lisent ATLAS_API_URL et ATLAS_API_KEY depuis l’environnement de votre serveur.
Paramètres
| Paramètre | Règles | Description |
|---|---|---|
q |
| Nom ou partie de nom recherché. |
lang |
| Langue préférée du nom affiché. |
categories |
| Ne garder que ces catégories. |
near |
| Point qui départage les résultats de même qualité. |
limit |
| Nombre maximal de résultats. |
Réponse
Dans une collection, id, geometry et properties décrivent chaque élément de features.
| Champ | Description |
|---|---|
features | Les résultats, dans l’ordre de l’API. |
id | Référence de source osm:{type}/{id}. Ce n’est pas un identifiant durable. |
geometry.coordinates | Position [longitude, latitude] en WGS84. |
properties.display | Nom à afficher (text, language, source_tag, fallback), ou null pour un lieu sans nom. |
properties.category.code | locality.<type> pour une localité, sinon une catégorie de lieu. |
properties.reference | Référence OSM (source, type, id, key). Elle peut changer d’un catalogue à l’autre. |
properties.match | Comment la requête a trouvé ce résultat : type de correspondance et nom correspondant. |
meta.status | ok avec des résultats, sinon no_match ; empty_catalog pour un catalogue de localités vide. |
meta.matched | Nombre de lieux correspondants avant la limite. |
meta.catalog.notices | Avertissements sur le catalogue, à refléter dans votre interface. |
meta.attribution | Mention à afficher partout où vous montrez ces données. |
Erreurs
Toutes les erreurs suivent le format Problem Details.
Lister les lieux d’une zone
GET/v1/places
Renvoie les lieux les plus proches du centre de la boîte.
- Accès requis
places:read- Réponse
application/geo+json
Exemples
cURL
curl --get "$ATLAS_API_URL/v1/places" \
--header "Authorization: Bearer $ATLAS_API_KEY" \
--data-urlencode 'bbox=-15.99,18.07,-15.95,18.11' \
--data-urlencode 'categories=healthcare' \
--data-urlencode 'lang=fr' \
--data-urlencode 'limit=100'Node.js
const url = new URL("/v1/places", process.env.ATLAS_API_URL);
url.search = new URLSearchParams({
bbox: "-15.99,18.07,-15.95,18.11",
categories: "healthcare",
lang: "fr",
limit: "100",
}).toString();
const response = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.ATLAS_API_KEY}` },
});
const body = await response.json();
if (!response.ok) throw new Error(`ATLASMR ${response.status} ${body.code}`);
console.log(body.meta.status, body.features.length);PHP
<?php
$url = getenv('ATLAS_API_URL') . '/v1/places?' . http_build_query([
'bbox' => '-15.99,18.07,-15.95,18.11',
'categories' => 'healthcare',
'lang' => 'fr',
'limit' => '100',
], '', '&', PHP_QUERY_RFC3986);
$curl = curl_init($url);
curl_setopt_array($curl, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ATLAS_API_KEY')],
]);
$body = json_decode(curl_exec($curl), true, 512, JSON_THROW_ON_ERROR);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
if ($status !== 200) {
throw new RuntimeException("ATLASMR {$status} {$body['code']}");
}
echo $body['meta']['status'], ' ', count($body['features']), PHP_EOL;Les exemples lisent ATLAS_API_URL et ATLAS_API_KEY depuis l’environnement de votre serveur.
Paramètres
| Paramètre | Règles | Description |
|---|---|---|
bbox |
| Zone à lister. |
categories |
| Ne garder que ces catégories. |
lang |
| Langue préférée du nom affiché. |
limit |
| Nombre maximal de lieux renvoyés. |
Réponse
Dans une collection, id, geometry et properties décrivent chaque élément de features.
| Champ | Description |
|---|---|
features | Les résultats, dans l’ordre de l’API. |
id | Référence de source osm:{type}/{id}. Ce n’est pas un identifiant durable. |
geometry.coordinates | Position [longitude, latitude] en WGS84. |
properties.display | Nom à afficher (text, language, source_tag, fallback), ou null pour un lieu sans nom. |
properties.category.code | locality.<type> pour une localité, sinon une catégorie de lieu. |
properties.position.kind | Origine de la position : point OSM, ou point calculé pour une surface. |
meta.status | ok avec des résultats, sinon no_match ; empty_catalog pour un catalogue de localités vide. |
meta.matched | Nombre de lieux correspondants avant la limite. |
meta.truncated | true quand matched dépasse limit : réduisez la zone ou filtrez. |
meta.catalog.notices | Avertissements sur le catalogue, à refléter dans votre interface. |
meta.attribution | Mention à afficher partout où vous montrez ces données. |
Erreurs
Toutes les erreurs suivent le format Problem Details.
Lire un lieu
GET/v1/places/osm/{type}/{id}
Renvoie un lieu par sa référence OSM, avec ses détails de source autorisés.
- Accès requis
places:read- Réponse
application/geo+json
Exemples
Construisez le chemin avec properties.reference.type et properties.reference.id d’un résultat de liste ou de recherche.
Paramètres
| Paramètre | Règles | Description |
|---|---|---|
type |
| Type de l’élément OSM. |
id |
| Identifiant de l’élément OSM. |
lang |
| Langue préférée du nom affiché. |
Réponse
| Champ | Description |
|---|---|
id | Référence de source osm:{type}/{id}. Ce n’est pas un identifiant durable. |
geometry.coordinates | Position [longitude, latitude] en WGS84. |
properties.display | Nom à afficher (text, language, source_tag, fallback), ou null pour un lieu sans nom. |
properties.names | Noms fournis par la source, par étiquette de langue, jamais traduits. |
properties.category.code | locality.<type> pour une localité, sinon une catégorie de lieu. |
properties.info | Détails de source autorisés, comme horaires ou téléphone, tels que la source les écrit. |
meta.catalog.notices | Avertissements sur le catalogue, à refléter dans votre interface. |
meta.attribution | Mention à afficher partout où vous montrez ces données. |
Erreurs
Toutes les erreurs suivent le format Problem Details.
Avertissements et attribution
Chaque réponse liste ses avertissements dans meta.catalog.notices :
experimental_catalog- Catalogue expérimental : son contenu et sa forme peuvent changer.
partial_coverage- Couverture partielle : un lieu absent peut exister.
unverified_source- Données de source que ATLASMR n’a pas vérifiées.
not_linked_to_map_release- Non lié à la version de la carte : positions et noms peuvent différer du fond de carte.
Les données viennent d’OpenStreetMap, sous licence ODbL 1.0. Affichez cette mention, avec son lien, partout où vous les montrez :