Maps Tools Resolution API

تُعدّ Maps Tools Resolution API جزءًا من أدوات تجربة الخرائط للوكلاء (المعروفة سابقًا باسم Maps Grounding Lite). وتوفّر نقاط نهاية مجمّعة تحوّل أسماء المواقع الجغرافية وعناوين URL في "خرائط Google" إلى أرقام تعريف الأماكن في "خرائط Google". يمكنك استخدام أرقام تعريف الأماكن التي تم عرضها مع واجهات برمجة التطبيقات الأخرى في "منصة خرائط Google". يتضمّن كل ردّ أيضًا رابطًا يحفظ الأماكن التي تم العثور عليها كقائمة في "خرائط Google".

تتوفّر Resolution API كطُرق REST وأدوات على خادم MCP لأدوات تجربة الخرائط للوكلاء:

قبل البدء

لاستخدام Resolution API، يجب أن يكون لديك مشروع على Google Cloud مع تفعيل الفوترة وخدمة واجهة برمجة التطبيقات أدوات وكيل تجربة "خرائط Google". للحصول على التعليمات، يُرجى الاطّلاع على المقالة تفعيل أدوات تجربة الخرائط للوكلاء في مشروعك على Google Cloud.

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

تتوافق Resolution API مع كلّ من مفتاح واجهة برمجة التطبيقات وبيانات اعتماد OAuth 2.0.

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

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

https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY

في الأمثلة الواردة في هذه الصفحة، استبدِل API_KEY بمفتاح واجهة برمجة التطبيقات.

نطاقات OAuth 2.0

في حال استخدام تفويض OAuth، يكون النطاق التالي متاحًا:

• https://www.googleapis.com/auth/maps-platform.mapstools

سقف الاستخدام

تنطبق الحصص التلقائية التالية على Resolution API:

• ‫ResolveNames: ‏600 طلب في الدقيقة لكل مشروع
• ‫ResolveMapsUrls: ‏600 طلب في الدقيقة لكل مشروع
• حجم الدفعة: ما يصل إلى 20 طلب بحث أو عنوان URL في كل طلب.

يتم احتساب كل طلب كطلب بحث واحد، بغض النظر عن عدد العناصر التي يحتوي عليها.

الأسعار

يتم إصدار فواتير الطلبات إلى ResolveNames وResolveMapsUrls بدون أي رسوم (0 دولار أمريكي) ضمن رمز التخزين التعريفي Places API Text Search Essentials (IDs Only). كما هو الحال مع بقية أدوات التجارب من "خرائط Google" للوكلاء، يجب أن يتضمّن مشروعك حساب فوترة.

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

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

• الحدّ الأقصى لحجم الدفعة: تسمح كلتا الطريقتَين بإضافة 20 سلعة كحدّ أقصى في كل طلب.
• متطلبات ResolveNames:
  • يجب أن يحدّد كل عنصر في queries مَعلمة text غير فارغة.
  • يجب أن تمثّل طلبات البحث اسم مكان أو عنوانًا محدّدًا، مثل "Googleplex, Mountain View, CA" أو "Eiffel Tower, Paris".
  • لا تتوفّر عمليات البحث العامة عن الفئات، مثل "restaurants in New York"، أو أسماء السلاسل العامة بدون موقع جغرافي، مثل "Starbucks"، وقد يتعذّر حلّها.
• متطلبات 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 التي لا تشير إلى مكان واحد فريد.

حفظ الأماكن التي تم حلّها في "خرائط Google"

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

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

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

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

تفسير الردّ

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

لا تفترض أنّ الدفعة بأكملها تعذّر تحميلها بسبب تعذُّر تحميل عنصر واحد. يُرجى دائمًا مراجعة failedRequests لمعرفة السلع التي تعذّر حلّ مشاكلها، إن وُجدت.

الأخطاء لكل سلعة

يسرد الجدول التالي الأخطاء لكل عنصر التي قد تظهر في failedRequests:

إعادة محاولة نقل العناصر التي تعذّر نقلها فقط باستخدام INTERNAL

الأخطاء على المستوى الأعلى

تعرض واجهة برمجة التطبيقات خطأً في المستوى الأعلى بدلاً من ردّ جزئي في الحالات التالية:

• طلب غير صالح (400 INVALID_ARGUMENT): يحتوي الطلب على أكثر من 20 عنصرًا، أو لا يتضمّن طلب ResolveNames أي طلبات بحث أو يتضمّن طلب بحث بقيمة text فارغة، أو يتضمّن طلب ResolveMapsUrls عنوان URL فارغًا أو عنوان URL غير صالح من الناحية النحوية. يؤدي عنصر واحد غير صالح إلى فشل الطلب بأكمله.
• أخطاء المصادقة أو الأذونات أو الحصص: على سبيل المثال، مفتاح واجهة برمجة التطبيقات غير متوفّر أو غير صالح، أو يتجاوز الطلب حدود الاستخدام.
• أخطاء في الخادم (500 INTERNAL): أعِد محاولة إرسال الطلب.

استخدام Resolution API مع MCP

يوفّر خادم MCP لأدوات تجربة الخرائط للوكلاء على الرابط https://mapstools.googleapis.com/mcp واجهة Resolution API كأداتَين:

• ‫resolve_names: تُحوّل مجموعة من أسماء المواقع الجغرافية أو عناوينها إلى أرقام تعريف الأماكن.
• resolve_maps_urls: تتيح هذه الطريقة تحويل مجموعة من عناوين URL على "خرائط Google" إلى أرقام تعريف أماكن.

عند ضبط نموذجك اللغوي الكبير لاستخدام خادم بروتوكول سياق النموذج (MCP)، تصبح هذه الأدوات متاحة إلى جانب أدوات وكيل التجارب من "خرائط Google" الأخرى. تقبل الأدوات المدخلات نفسها، وتفرض القيود نفسها، وتعرض استجابة الفشل الجزئي نفسها مثل طرق REST.

تتضمّن ردود الأداة الحقل save_to_maps_url. توجّه أوصاف الأدوات النموذج اللغوي الكبير إلى عرض هذا الرابط عندما يريد المستخدم حفظ الأماكن التي تم حلّها أو مشاركتها أو فتحها كقائمة في "خرائط Google"، بدلاً من إنشاء رابط بنفسه.

يستخدم المثال التالي curl لاستدعاء أداة resolve_names مباشرةً:

curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--header 'X-Goog-Api-Key: API_KEY' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_names",
    "arguments": {
      "queries": [
        { "text": "Googleplex, Mountain View, CA" },
        { "text": "Eiffel Tower, Paris" }
      ]
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

للاتصال بـ resolve_maps_urls، اضبط name على resolve_maps_urls ومرِّر مصفوفة urls في arguments.

مواصفات REST API وأمثلة على curl

ResolveNames

الطريقة: POST

https://mapstools.googleapis.com/v1: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/v1:resolveNames?key=API_KEY"

استجابة JSON

{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw,ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

مثال على 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/v1:resolveNames?key=API_KEY"

استجابة JSON

{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

ResolveMapsUrls

الطريقة: POST

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

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

{
  "urls": [
    "string"
  ]
}

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

مثال على Curl: حلّ ناجح

يحلّ المثال التالي عنوان URL عاديًا لمكان على "خرائط 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!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

استجابة JSON

{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

مثال على 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!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

استجابة JSON

{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Failed to resolve Maps URL to a place."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

مثال على 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/v1:resolveMapsUrls?key=API_KEY"

استجابة JSON

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

إرسال ملاحظات

للإبلاغ عن مشكلة أو مشاركة ملاحظات حول Resolution API، استخدِم مكوّن أداة تتبُّع المشاكل المتاحة للجميع في أدوات تجربة الخرائط للوكلاء:

• الإبلاغ عن خطأ
• إرسال طلب ميزة
• إرسال ملاحظات