GET · /api/v1/search/suggest

Search API

End-user search flow with three complementary endpoints: typeahead suggestions, full place retrieval, and reverse geocoding. Suggestions and retrievals can share a session token so a whole search session is billed as a single event.

Suggest (Typeahead)

Return lightweight suggestions for a partial query (minimum 2 characters). Results do not contain coordinates — call /search/retrieve/:place_id to resolve a chosen suggestion into a full place.

GET/search/suggest

Typeahead place suggestions for a partial query

Parameters

NameTypeDescription
qstringSearch query (minimum 2 characters)
languagestring?Response language: fr, ar, or en
session_tokenstring?UUID v4 used to group suggest + retrieve into one billed session
proximitystring?Proximity bias as "longitude,latitude" (note the order)
countrystring?ISO-3166 alpha-2 country code to filter results

Example Request

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()

Example Response

[
  {
    "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"
    }
  }
]

Retrieve Place

Resolve a place_id returned by /search/suggest into a full place record, including coordinates and multilingual fields. Pass the same session_token you used for /search/suggest so the two calls are billed together.

GET/search/retrieve/:place_id

Resolve a place_id from a suggestion into a full place

Path Parameters

NameTypeDescription
place_idstringPlace identifier returned by /search/suggest (OSM N/W/R id or Pelias gid)

Query Parameters

NameTypeDescription
session_tokenstring?Same UUID v4 passed to /search/suggest for this session

Example Request

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()

Example Response

{
  "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"
  }
}

Reverse Search

Reverse geocode a coordinate pair into one or more place records, optionally filtered by feature type (poi, address, place).

GET/search/reverse

Reverse geocode coordinates to place records

Parameters

NameTypeDescription
lngnumberLongitude to reverse geocode
latnumberLatitude to reverse geocode
languagestring?Response language: fr, ar, or en
limitnumber?Max results, 1–10
typesstring?Comma-separated feature types (e.g. poi,address,place)

Example Request

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()

Example Response

[
  {
    "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"
    }
  }
]

Tips

Session Tokens

Generate a fresh UUID v4 at the start of each user search session and pass it as session_token on every /search/suggest call plus the final /search/retrieve. All calls with the same token are billed as one search event.

Proximity Bias

When you know the user's location, pass proximity=lng,lat on /search/suggest to boost results near them. Coordinates are in longitude,latitude order (not lat,lng).

Multilingual Names

Every result includes names in French, Arabic, and English when available. The language parameter controls the default display language but does not filter matches — users can type in any language.