Guide de démarrage

Ouvrez votre espace

Connectez-vous à la console avec une adresse e-mail vérifiée, puis créez ou choisissez votre organisation.

Créez un projet

Un projet regroupe vos clés. Elles partagent ses limites de débit.

Créez une clé sandbox

Dans l’onglet Clés API du projet, choisissez l’accès search:read ou places:read et une durée. La clé n’est affichée qu’une fois : enregistrez-la aussitôt dans le gestionnaire de secrets de votre serveur.

Préparez l’environnement

Les exemples lisent ATLAS_API_URL et ATLAS_API_KEY depuis l’environnement. read -rs saisit la clé sans l’afficher ni l’écrire dans l’historique du shell.

read -rs ATLAS_API_KEY && export ATLAS_API_KEY

L’adresse de l’API vous est communiquée à l’ouverture de votre accès. Définissez alors ATLAS_API_URL avec cette adresse, sans barre oblique finale.

Envoyez une première requête

Appelez l’API depuis votre serveur. Elle n’envoie pas d’en-têtes CORS, et une clé secrète ne doit jamais atteindre un navigateur.

curl --get "$ATLAS_API_URL/v1/localities/search" \
  --header "Authorization: Bearer $ATLAS_API_KEY" \
  --data-urlencode 'q=Atar' \
  --data-urlencode 'lang=fr' \
  --data-urlencode 'limit=5'

const url = new URL("/v1/localities/search", process.env.ATLAS_API_URL);
url.search = new URLSearchParams({
  q: "Atar",
  lang: "fr",
  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

$url = getenv('ATLAS_API_URL') . '/v1/localities/search?' . http_build_query([
    'q' => 'Atar',
    'lang' => 'fr',
    '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;

Lisez la réponse

Une réponse 200 est une FeatureCollection GeoJSON servie en application/geo+json.

• meta.status vaut ok, no_match ou empty_catalog.
• Chaque résultat donne sa position en [longitude, latitude] et ses noms tels que la source les écrit.
• Affichez meta.attribution partout où vous montrez ces données.
• Une erreur suit le format Problem Details : lisez son code, jamais son texte.