Maps Tools Resolution API (تجريبية)

توفّر واجهة برمجة التطبيقات Maps Tools Resolution API نقاط نهاية للمعالجة على دفعات من أجل تحليل أسماء المواقع الجغرافية وعناوين URL إلى أرقام تعريف الأماكن على "خرائط Google".

الوصول إلى واجهة برمجة التطبيقات والمصادقة

تجريبية: إنّ واجهتَي ResolveNames وResolveMapsUrls API في مرحلة تجريبية (ما قبل التوفّر للجمهور العام). قد يكون الدعم المقدّم للمنتجات والميزات في مرحلة ما قبل التوفّر للجمهور العام محدودًا، وقد لا تكون التغييرات التي يتم إجراؤها على المنتجات والميزات هنا متوافقة مع الإصدارات الأخرى من هذه المرحلة. تخضع عروض مرحلة ما قبل التوفّر للجمهور العام لبنود الخدمة المحدّدة في "منصة خرائط Google". لمزيد من المعلومات، يُرجى الاطّلاع على أوصاف مراحل الإطلاق. لا يتم تحصيل أي رسوم مقابل استخدام خدمتَي ResolveNames وResolveMapsUrls أثناء توفّرهما في مرحلة Experimental.

طُرق المصادقة

تتوافق واجهات برمجة التطبيقات مع بيانات اعتماد مفتاح واجهة برمجة التطبيقات وOAuth 2.0:

1. مفتاح واجهة برمجة التطبيقات

يمكنك مصادقة الطلبات من خلال إضافة مفتاح صالح لواجهة برمجة التطبيقات لمنصة خرائط Google إلى عنوان URL للطلب أو في عنوان X-Goog-Api-Key:

https://mapstools.googleapis.com/v1alpha:resolveNames?key=YOUR_API_KEY

2. نطاقات OAuth 2.0

في حال استخدام تفويض OAuth، تتوفّر النطاقات التالية:

• https://www.googleapis.com/auth/maps-platform.mapstools (مستحسن)

التحقّق من صحة الطلب والقيود

لمنع التحميل الزائد وضمان سرعة الاستجابة، يتم التحقّق من صحة الطلبات المجمّعة بدقة:

• الحد الأقصى لحجم المجموعة: يتيح كلا واجهتَي برمجة التطبيقات 20 عنصرًا كحدّ أقصى لكل طلب.
• متطلبات ResolveNames:
  • يجب أن يحدّد كل عنصر من عناصر طلبات البحث مَعلمة نصية غير فارغة.
  • يجب أن تمثّل طلبات البحث اسم مكان أو عنوانًا محدّدًا (مثل "Googleplex، ماونتن فيو، كاليفورنيا" أو "برج إيفل، باريس").
  • لا تتوافق عمليات البحث العامة حسب الفئة (مثل "مطاعم في نيويورك") أو أسماء السلاسل العامة بدون موقع جغرافي (مثل "ستاربكس") وقد يتعذّر حلّها.
• متطلبات ResolveMapsUrls:
  • يجب أن يكون كل عنوان URL صالحًا من الناحية البنيوية في "خرائط Google".
  • تشمل التنسيقات المتوافقة ما يلي:
    • عنوان URL العادي للمكان: https://www.google.com/maps/place/...
    • عنوان URL المختصَر: https://maps.app.goo.gl/...
  • لا تتوافق عناوين URL العامة المستندة إلى طلب البحث في "خرائط Google" (مثل https://maps.google.com/?q=restaurant) وعناوين URL التي لا تشير إلى مكان فريد واحد.

التعامل مع الأخطاء الجزئية

تم تصميم كلتا واجهتَي برمجة التطبيقات كمعالجَين مجمّعين. إذا تعذّر حلّ بعض العناصر في دفعة، لن يتعذّر تنفيذ الطلب بشكل عام بسبب حدوث خطأ على المستوى الأعلى. بدلاً من ذلك، تعرض واجهة برمجة التطبيقات الاستجابة نجاح جزئي.

كيفية تفسير الردّ

1. التطابق التام بنسبة 1:1: تتطابق النتائج المعروضة (بالنسبة إلى ResolveNames) أو قوائم الكيانات (بالنسبة إلى ResolveMapsUrls) بنسبة 1:1 مع قائمة الإدخال.
2. العناصر الفارغة في حال حدوث أخطاء: إذا تعذّر تحليل عنصر في الفهرس i، ستتضمّن قائمة النتائج عنصرًا فارغًا {} في الفهرس i.
3. خريطة failedRequests: يحتوي الردّ على خريطة failedRequests.
   • المفتاح هو الفهرس المستند إلى الرقم 0 للعنصر الذي تعذّر تحميله (يتم تمثيله كسلسلة في JSON).
   • القيمة هي عنصر google.rpc.Status يحتوي على رمز الخطأ المحدّد (من حالات gRPC/HTTP العادية) ورسالة تفصيلية توضّح سبب تعذُّر التنفيذ.

حالات الفشل على المستوى الأعلى

لا يتم عرض خطأ HTTP من المستوى الأعلى (مثل 400 Bad Request) إلا إذا تعذّر التحقّق من صحة الطلب (مثلاً، عند إدخال أكثر من 20 عنصرًا أو عدم توفّر الحقول المطلوبة).

مواصفات واجهة برمجة التطبيقات وأمثلة Curl

1. ResolveNames API

الطريقة: POST

https://mapstools.googleapis.com/v1alpha:resolveNames

تنسيق نص الطلب

{
  "queries": [
    { "text": "string" }
  ],
  "locationBias": {
    "viewport": {
      "low": { "latitude": number, "longitude": number },
      "high": { "latitude": number, "longitude": number }
    }
  },
  "regionCode": "string"
}

• ‫queries (مطلوب): قائمة متكرّرة من طلبات البحث التي يجب حلّها (20 طلب بحث كحدّ أقصى).
• locationBias (اختياري): مربّع الإحاطة لإطار العرض من أجل توجيه النتائج نحو منطقة محلية.
• regionCode (اختياري): رمز CLDR للبلد (مثل "US" أو "FR") لتحديد النتائج.

مثال على Curl: استجابة ناجحة

يؤدي طلب البحث هذا إلى حلّ "Googleplex" و "برج إيفل".

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "Googleplex, Mountain View, CA" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveNames?key=KEY"

استجابة JSON

{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ]
}

مثال على Curl: نتائج مختلطة (تعذُّر جزئي)

في هذا المثال، العنصر الأول هو نص غير قابل للحل، والعنصر الثاني هو مكان صالح.

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "This is not a real place name at all 123456789" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveNames?key=KEY"

استجابة JSON

{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  }
}

2. ResolveMapsUrls API

الطريقة: POST

https://mapstools.googleapis.com/v1alpha:resolveMapsUrls

تنسيق نص الطلب

{
  "urls": [
    "string"
  ]
}

• urls (مطلوب): قائمة متكرّرة بسلاسل عناوين URL على "خرائط Google" التي يجب حلّها (20 كحدّ أقصى).

مثال على Curl: الاستجابة الناجحة

حلّ رابط عادي لمكان على "خرائط Google"

curl -X POST \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"

استجابة JSON

{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    }
  ]
}

مثال على Curl: نتائج مختلطة (تعذُّر جزئي)

حلّ عنوان URL صالح لمكان واحد وعنوان URL واحد غير صالح/غير متوافق

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "urls": [
    "https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"

استجابة JSON

{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Invalid URL."
    }
  }
}

مثال على Curl: تعذُّر التحقّق من الصحة

محاولة إرسال أكثر من 20 عنوان URL في طلب واحد

python3 -c 'import json; print(json.dumps({"urls": ["https://www.google.com/maps/place/Googleplex"] * 21}))' | \
curl -X POST \
-H "Content-Type: application/json" \
-d @- \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"

استجابة JSON

{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}