GET · /api/v1/geocode/forward

Geocoding API

Convert addresses to coordinates and coordinates to addresses using the Oolel/Pelias geocoder. All results include multilingual names (French, Arabic, English) and a normalized coordinate pair in [longitude, latitude] order.

Forward Geocoding

Convert an address or place name into coordinates. Matches are ranked by the geocoder's own confidence and may be restricted to a specific country using the ISO-3166 alpha-2 country code.

GET/geocode/forward

Geocode an address or place name to coordinates

Parameters

Name	Type	Description
address	string	Address or place name to geocode
country	string?	ISO-3166 alpha-2 country code (e.g. MR, SN) to bias or filter results

Example Request

cURLbash

curl -X GET "https://api.oolelmaps.com/api/v1/geocode/forward?address=Tevragh+Zeina+Nouakchott&country=MR" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScriptjavascript

const response = await fetch(
  "https://api.oolelmaps.com/api/v1/geocode/forward?" +
    new URLSearchParams({
      address: "Tevragh Zeina Nouakchott",
      country: "MR",
    }),
  {
    headers: { Authorization: "Bearer YOUR_API_KEY" },
  },
);

const results = await response.json();

Pythonpython

import requests

response = requests.get(
    "https://api.oolelmaps.com/api/v1/geocode/forward",
    params={"address": "Tevragh Zeina Nouakchott", "country": "MR"},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

results = response.json()

Example Response

[
  {
    "id": "56b20674-238d-4723-bc28-203f7e4d04f9",
    "code": "W2TBFB",
    "lotissement": "Ilot T",
    "ilot": null,
    "lotNumber": "39",
    "streetName": {
      "ar": "جمال عبد الناصر",
      "en": "Gamal Abdel Nasser",
      "fr": "Gemal Abdel Nasser"
    },
    "buildingName": null,
    "identifierPrecise": {
      "ar": "39 شارع جمال عبد الناصر",
      "en": "39 Gemal Abdel Nasser Avenue",
      "fr": "39 Avenue Gemal Abdel Nasser"
    },
    "description": null,
    "landmarks": null,
    "latitude": 18.088250412537,
    "longitude": -15.9798102142324,
    "countryId": "1fe04eb6-066e-4533-9369-81338bf107b9",
    "adminLevel3Id": "ec4e1484-6df7-4eed-a50f-b95105a28ad9",
    "verificationStatus": "ADMIN_VERIFIED",
    "verificationCount": 0,
    "photoUrls": [],
    "isActive": true,
    "version": 3
  }
]

Reverse Geocoding

Return the nearest place or address to a latitude/longitude pair. Useful for identifying what is at a point the user tapped on the map.

GET/geocode/reverse

Reverse geocode coordinates to the nearest place

Parameters

Name	Type	Description
lat	number	Latitude of the point to reverse geocode
lng	number	Longitude of the point to reverse geocode
country	string?	ISO-3166 alpha-2 country code (e.g. MR, SN) to bias or filter results

Example Request

cURLbash

curl -X GET "https://api.oolelmaps.com/api/v1/geocode/reverse?lat=18.0858&lng=-15.9785&country=MR" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScriptjavascript

const response = await fetch(
  "https://api.oolelmaps.com/api/v1/geocode/reverse?" +
    new URLSearchParams({ lat: "18.0858", lng: "-15.9785", country: "MR" }),
  { headers: { Authorization: "Bearer YOUR_API_KEY" } },
);

const results = await response.json();

Pythonpython

import requests

response = requests.get(
    "https://api.oolelmaps.com/api/v1/geocode/reverse",
    params={"lat": 18.0858, "lng": -15.9785, "country": "MR"},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

results = response.json()

Example Response

{
  "id": "dd808201-7106-4730-a646-56fff1d4de37",
  "code": "W2TBFD",
  "identifierPrecise": {
    "ar": "47 شارع جمال عبد الناصر",
    "en": "47 Gemal Abdel Nasser Avenue",
    "fr": "47 Avenue Gemal Abdel Nasser"
  },
  "latitude": 18.0882428323741,
  "longitude": -15.9782648035898,
  "countryId": "1fe04eb6-066e-4533-9369-81338bf107b9",
  "distance_meters": 271.51986951,
  "places": []
}

Autocomplete

Lightweight prefix suggestions suitable for typeahead/search-as-you-type inputs. Results are not full records; use the Search API's retrieve endpoint if you need coordinates and full details.

GET/geocode/autocomplete

Return prefix-matched place suggestions for a partial query

Parameters

Name	Type	Description
text	string	Query text (partial for autocomplete, full for search)
country	string?	ISO-3166 alpha-2 country code (e.g. MR, SN) to bias or filter results

Example Request

cURLbash

curl -X GET "https://api.oolelmaps.com/api/v1/geocode/autocomplete?text=tevra&country=MR" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScriptjavascript

const response = await fetch(
  "https://api.oolelmaps.com/api/v1/geocode/autocomplete?" +
    new URLSearchParams({ text: "tevra", country: "MR" }),
  { headers: { Authorization: "Bearer YOUR_API_KEY" } },
);

const suggestions = await response.json();

Pythonpython

import requests

response = requests.get(
    "https://api.oolelmaps.com/api/v1/geocode/autocomplete",
    params={"text": "tevra", "country": "MR"},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

suggestions = response.json()

Example Response

[
  {
    "id": "56b20674-238d-4723-bc28-203f7e4d04f9",
    "code": "W2TBFB",
    "lotissement": "Ilot T",
    "ilot": null,
    "lotNumber": "39",
    "streetName": {
      "ar": "جمال عبد الناصر",
      "en": "Gamal Abdel Nasser",
      "fr": "Gemal Abdel Nasser"
    },
    "buildingName": null,
    "identifierPrecise": {
      "ar": "39 شارع جمال عبد الناصر",
      "en": "39 Gemal Abdel Nasser Avenue",
      "fr": "39 Avenue Gemal Abdel Nasser"
    },
    "description": null,
    "landmarks": null,
    "latitude": 18.088250412537,
    "longitude": -15.9798102142324,
    "countryId": "1fe04eb6-066e-4533-9369-81338bf107b9",
    "adminLevel3Id": "ec4e1484-6df7-4eed-a50f-b95105a28ad9",
    "verificationStatus": "ADMIN_VERIFIED",
    "verificationCount": 0,
    "photoUrls": [],
    "isActive": true,
    "version": 3
  }
]

Full-Text Search

Run a full-text search against the Pelias index. Use this when you already have a complete query string and want ranked results rather than prefix suggestions.

GET/geocode/search

Full-text search against the Pelias index

Parameters

Name	Type	Description
text	string	Query text (partial for autocomplete, full for search)
language	string?	Response language: fr, ar, or en

Example Request

cURLbash

curl -X GET "https://api.oolelmaps.com/api/v1/geocode/search?text=Marche+Capitale&language=fr" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScriptjavascript

const response = await fetch(
  "https://api.oolelmaps.com/api/v1/geocode/search?" +
    new URLSearchParams({ text: "Marche Capitale", language: "fr" }),
  { headers: { Authorization: "Bearer YOUR_API_KEY" } },
);

const results = await response.json();

Pythonpython

import requests

response = requests.get(
    "https://api.oolelmaps.com/api/v1/geocode/search",
    params={"text": "Marche Capitale", "language": "fr"},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

results = response.json()

Example Response

[
  {
    "id": "oolel:address:addr-dd808201-7106-4730-a646-56fff1d4de37",
    "placeId": "17950eb4-1af6-43cc-ae52-5ab6f1cc663b",
    "addressId": "dd808201-7106-4730-a646-56fff1d4de37",
    "placeName": "47 Avenue Gemal Abdel Nasser, Tevragh Zeina, Nouakchott, Mauritania",
    "coordinates": [-15.978265, 18.088243],
    "placeType": "address",
    "text": "47 Avenue Gemal Abdel Nasser",
    "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"
    }
  }
]