GET · /api/v1/search/suggest

واجهة البحث

تدفق بحث لمستخدم نهائي مع ثلاث نقاط تكميلية: اقتراحات أثناء الكتابة، واسترجاع كامل للمكان، وترميز عكسي. يمكن أن تتشارك الاقتراحات والاسترجاع رمز جلسة واحد حتى تُحتسب جلسة البحث كاملة كحدث واحد.

الاقتراحات (أثناء الكتابة)

يعيد اقتراحات خفيفة لاستعلام جزئي (حدّ أدنى 2 حرف). لا تحتوي النتائج على إحداثيات — نادِ /search/retrieve/:place_id لتحويل اقتراح مختار إلى مكان كامل.

GET/search/suggest

اقتراحات أماكن أثناء الكتابة لاستعلام جزئي

المعاملات

Name	Type	Description
q	string	استعلام البحث (حدّ أدنى 2 حرف)
language	string?	لغة الاستجابة: fr أو ar أو en
session_token	string?	UUID v4 لدمج suggest + retrieve في جلسة واحدة مفوترة
proximity	string?	تحيّز القرب بصيغة «خط الطول،خط العرض»
country	string?	رمز ISO-3166 alpha-2 لتصفية النتائج

مثال على الطلب

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

مثال على الاستجابة

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

استرجاع مكان

يحوّل place_id الذي أعاده /search/suggest إلى سجل مكان كامل بالإحداثيات والحقول متعددة اللغات. مرّر نفس session_token المستخدم مع /search/suggest لكي تُحتسب المكالمات معًا.

GET/search/retrieve/:place_id

تحويل place_id من اقتراح إلى سجل كامل

معاملات المسار

Name	Type	Description
place_id	string	المعرّف الذي يعيده /search/suggest (معرّف OSM N/W/R أو gid من Pelias)

معاملات الاستعلام

Name	Type	Description
session_token	string?	نفس UUID v4 الممرَّر إلى /search/suggest لهذه الجلسة

مثال على الطلب

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

مثال على الاستجابة

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

البحث العكسي

يُرمِّز زوج إحداثيات عكسيًا إلى سجل مكان واحد أو أكثر، مع تصفية اختيارية حسب نوع المعلم (poi, address, place).

GET/search/reverse

ترميز عكسي للإحداثيات إلى سجلات أماكن

المعاملات

Name	Type	Description
lng	number	خط الطول للترميز العكسي
lat	number	خط العرض للترميز العكسي
language	string?	لغة الاستجابة: fr أو ar أو en
limit	number?	الحد الأقصى للنتائج، 1–10
types	string?	أنواع معالم مفصولة بفواصل (مثل poi,address,place)

مثال على الطلب

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

مثال على الاستجابة

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

نصائح

رموز الجلسة

أنشئ UUID v4 جديد في بداية كل جلسة بحث ومرّره في session_token على كل /search/suggest وعلى /search/retrieve النهائي. كل المكالمات بالرمز نفسه تُحتسب كحدث واحد.

تحيّز القرب

عندما تعرف موقع المستخدم، مرّر proximity=lng,lat في /search/suggest لترجيح النتائج القريبة. الترتيب هو خط الطول،خط العرض (لا العكس).

أسماء متعددة اللغات

تتضمن كل نتيجة، عند توفرها، أسماء بالفرنسية والعربية والإنجليزية. يتحكم المعامل language بلغة العرض الافتراضية فقط ولا يفلتر التطابقات — يمكن للمستخدم الكتابة بأي لغة.