GET · /api/v1/search/suggest

API de recherche

Parcours de recherche côté utilisateur avec trois endpoints complémentaires : suggestions à la frappe, récupération complète d'un lieu et géocodage inverse. Les suggestions et les récupérations peuvent partager un jeton de session afin qu'une session de recherche entière soit facturée comme un seul événement.

Suggestions (typeahead)

Renvoie des suggestions légères pour une requête partielle (minimum 2 caractères). Les résultats ne contiennent pas de coordonnées — appelez /search/retrieve/:place_id pour transformer une suggestion choisie en fiche complète.

GET/search/suggest

Suggestions de lieux à la frappe pour une requête partielle

Paramètres

NameTypeDescription
qstringRequête de recherche (minimum 2 caractères)
languagestring?Langue de la réponse : fr, ar ou en
session_tokenstring?UUID v4 pour regrouper suggest + retrieve en une seule session facturée
proximitystring?Biais de proximité au format « longitude,latitude »
countrystring?Code pays ISO-3166 alpha-2 pour filtrer les résultats

Exemple de requête

cURLbash
curl -X GET "https://api.oolelmaps.com/api/v1/search/suggest?q=pharmacie&language=fr&proximity=-15.9785,18.0858&country=MR&session_token=b3b1a1c0-1234-4cab-9abc-0123456789ab" \
  -H "Authorization: Bearer YOUR_API_KEY"
JavaScriptjavascript
const sessionToken = crypto.randomUUID();

const response = await fetch(
  "https://api.oolelmaps.com/api/v1/search/suggest?" +
    new URLSearchParams({
      q: "pharmacie",
      language: "fr",
      proximity: "-15.9785,18.0858",
      country: "MR",
      session_token: sessionToken,
    }),
  { headers: { Authorization: "Bearer YOUR_API_KEY" } },
);

const suggestions = await response.json();
Pythonpython
import uuid, requests

session_token = str(uuid.uuid4())

response = requests.get(
    "https://api.oolelmaps.com/api/v1/search/suggest",
    params={
        "q": "pharmacie",
        "language": "fr",
        "proximity": "-15.9785,18.0858",
        "country": "MR",
        "session_token": session_token,
    },
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

suggestions = response.json()

Exemple de réponse

[
  {
    "id": "oolel:venue:place-17950eb4-1af6-43cc-ae52-5ab6f1cc663b",
    "placeId": "17950eb4-1af6-43cc-ae52-5ab6f1cc663b",
    "addressId": "17a0aa0e-761a-433e-b501-425a72f2111f",
    "name": "Palais présidentiel cafe food coffee food",
    "placeName": "Palais présidentiel, Nouakchott, Mauritania",
    "placeType": "venue",
    "coordinates": [-15.974456, 18.023607],
    "category": "venue",
    "distance": 6.295,
    "locality": "Riyadh",
    "postalcode": "U2RKMF",
    "region": "Nouakchott Sud",
    "regionAbbr": "NS",
    "country": "Mauritanie",
    "countryCode": "MR",
    "names": {
      "fr": "Palais présidentiel"
    },
    "lotissement": "Test A",
    "localities": {
      "fr": "Riyadh",
      "ar": "الرياض",
      "en": "Riyadh"
    },
    "regions": {
      "fr": "Nouakchott Sud",
      "ar": "نواكشوط الجنوبية",
      "en": "Nouakchott Sud"
    },
    "countries": {
      "fr": "Mauritanie",
      "ar": "موريتانيا",
      "en": "Mauritania"
    }
  }
]

Récupération d'un lieu

Transforme un place_id renvoyé par /search/suggest en fiche complète, avec coordonnées et champs multilingues. Passez le même session_token utilisé pour /search/suggest afin que les appels soient regroupés en une seule session facturée.

GET/search/retrieve/:place_id

Résout un place_id d'une suggestion en fiche complète

Paramètres de chemin

NameTypeDescription
place_idstringIdentifiant renvoyé par /search/suggest (id OSM N/W/R ou gid Pelias)

Paramètres de requête

NameTypeDescription
session_tokenstring?Même UUID v4 que celui passé à /search/suggest pour cette session

Exemple de requête

cURLbash
curl -X GET "https://api.oolelmaps.com/api/v1/search/retrieve/N9876543?session_token=b3b1a1c0-1234-4cab-9abc-0123456789ab" \
  -H "Authorization: Bearer YOUR_API_KEY"
JavaScriptjavascript
const placeId = "N9876543";
const response = await fetch(
  `https://api.oolelmaps.com/api/v1/search/retrieve/${placeId}?session_token=${sessionToken}`,
  { headers: { Authorization: "Bearer YOUR_API_KEY" } },
);

const place = await response.json();
Pythonpython
import requests

place_id = "N9876543"
response = requests.get(
    f"https://api.oolelmaps.com/api/v1/search/retrieve/{place_id}",
    params={"session_token": session_token},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

place = response.json()

Exemple de réponse

{
  "id": "oolel:venue:place-17950eb4-1af6-43cc-ae52-5ab6f1cc663b",
  "placeId": "17950eb4-1af6-43cc-ae52-5ab6f1cc663b",
  "addressId": "17a0aa0e-761a-433e-b501-425a72f2111f",
  "name": "Palais présidentiel",
  "placeName": "Palais présidentiel, Nouakchott, Mauritania",
  "placeType": "venue",
  "coordinates": [-15.974456, 18.023607],
  "category": "venue",
  "locality": "Riyadh",
  "postalcode": "U2RKMF",
  "region": "Nouakchott Sud",
  "regionAbbr": "NS",
  "country": "Mauritanie",
  "countryCode": "MR",
  "names": {
    "fr": "Palais présidentiel"
  },
  "localities": {
    "fr": "Riyadh",
    "ar": "الرياض",
    "en": "Riyadh"
  },
  "regions": {
    "fr": "Nouakchott Sud",
    "ar": "نواكشوط الجنوبية",
    "en": "Nouakchott Sud"
  },
  "countries": {
    "fr": "Mauritanie",
    "ar": "موريتانيا",
    "en": "Mauritania"
  }
}

Recherche inverse

Géocode une paire de coordonnées en une ou plusieurs fiches, avec un filtre optionnel par type (poi, address, place).

GET/search/reverse

Géocodage inverse de coordonnées vers des fiches

Paramètres

NameTypeDescription
lngnumberLongitude à géocoder en inverse
latnumberLatitude à géocoder en inverse
languagestring?Langue de la réponse : fr, ar ou en
limitnumber?Nombre maximum de résultats, 1–10
typesstring?Types de features séparés par des virgules (ex. poi,address,place)

Exemple de requête

cURLbash
curl -X GET "https://api.oolelmaps.com/api/v1/search/reverse?lng=-15.9785&lat=18.0858&language=fr&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"
JavaScriptjavascript
const response = await fetch(
  "https://api.oolelmaps.com/api/v1/search/reverse?" +
    new URLSearchParams({
      lng: "-15.9785",
      lat: "18.0858",
      language: "fr",
      limit: "5",
    }),
  { headers: { Authorization: "Bearer YOUR_API_KEY" } },
);

const results = await response.json();
Pythonpython
import requests

response = requests.get(
    "https://api.oolelmaps.com/api/v1/search/reverse",
    params={"lng": -15.9785, "lat": 18.0858, "language": "fr", "limit": 5},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

results = response.json()

Exemple de réponse

[
  {
    "id": "oolel:address:addr-dd808201-7106-4730-a646-56fff1d4de37",
    "addressId": "dd808201-7106-4730-a646-56fff1d4de37",
    "name": "47 Avenue Gemal Abdel Nasser",
    "placeName": "47 Avenue Gemal Abdel Nasser, Tevragh Zeina, Nouakchott, Mauritania",
    "placeType": "address",
    "coordinates": [-15.978265, 18.088243],
    "category": "address",
    "distance": 0.273,
    "locality": "Tevragh Zeina",
    "postalcode": "W2TBFD",
    "region": "Nouakchott Ouest",
    "regionAbbr": "NO",
    "country": "Mauritanie",
    "countryCode": "MR",
    "names": {
      "fr": "47 Avenue Gemal Abdel Nasser",
      "ar": "47 شارع جمال عبد الناصر",
      "en": "47 Gemal Abdel Nasser Avenue"
    },
    "lotissement": "Ilot T",
    "localities": {
      "fr": "Tevragh Zeina",
      "ar": "تفرغ زينة",
      "en": "Tevragh Zeina"
    },
    "regions": {
      "fr": "Nouakchott Ouest",
      "ar": "نواكشوط الغربية",
      "en": "Nouakchott Ouest"
    },
    "countries": {
      "fr": "Mauritanie",
      "ar": "موريتانيا",
      "en": "Mauritania"
    }
  }
]

Conseils

Jetons de session

Générez un UUID v4 au début de chaque session de recherche et passez-le dans session_token sur chaque /search/suggest et sur le /search/retrieve final. Tous les appels partageant le même jeton sont facturés comme un seul événement.

Biais de proximité

Lorsque vous connaissez la position de l'utilisateur, passez proximity=lng,lat sur /search/suggest pour favoriser les résultats proches. L'ordre est longitude,latitude (et non l'inverse).

Noms multilingues

Chaque résultat inclut, lorsque disponible, des noms en français, en arabe et en anglais. Le paramètre language contrôle la langue d'affichage par défaut mais ne filtre pas les correspondances — l'utilisateur peut saisir dans n'importe quelle langue.