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

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

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

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

طرق المصادقة

تتوافق واجهات برمجة التطبيقات مع بيانات اعتماد مفتاح واجهة برمجة التطبيقات وبروتوكول 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:
  • يجب أن تحدّد كل عنصر من عناصر `queries` مَعلمة `text` غير فارغة.
  • يجب أن تمثّل طلبات البحث اسم مكان أو عنوانًا محدّدًا (مثل "Googleplex, Mountain View, CA" أو "برج إيفل، باريس").
  • لا يتم دعم عمليات البحث العامة حسب الفئة (مثل "مطاعم في نيويورك") أو أسماء السلاسل العامة بدون موقع جغرافي (مثل "ستاربكس") وقد يتعذّر حلّها.
• متطلبات ResolveMapsUrls:
  • يجب أن يكون كل عنوان URL عنوان 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.
   • المفتاح هو الفهرس المستند إلى الصفر للعنصر الذي تعذّر (ممثلاً كسلسلة في JSON).
   • القيمة هي كائن google.rpc.Status يحتوي على رمز الخطأ المحدّد (من حالات gRPC/HTTP العادية) ورسالة تفصيلية توضّح سبب تعذّر حلّ المشكلة.

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

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

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

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

الطريقة: 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

الطريقة: 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"
  }
}