Maps Tools Resolution API

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

تتوفّر واجهة Resolution API كطُرق REST وأدوات على خادم Maps Grounding Lite MCP:

قبل البدء

لاستخدام Resolution API، يجب أن يكون لديك مشروع على Google Cloud تم تفعيل الفوترة فيه وخدمة واجهة برمجة التطبيقات Maps Grounding Lite. للحصول على التعليمات، يُرجى الاطّلاع على مقالة تفعيل خدمة Maps Grounding Lite في مشروعك على 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). كما هو الحال مع بقية ميزات Maps Grounding Lite، يجب أن يكون لمشروعك حساب فوترة.

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

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

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

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

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

عند ضبط نموذج LLM لاستخدام خادم Maps Grounding Lite MCP، تصبح هذه الأدوات متاحة إلى جانب أدوات Maps Grounding Lite الأخرى. تقبل الأدوات المدخلات نفسها، وتفرض القيود نفسها، وتعرض استجابة الفشل الجزئي نفسها التي تعرضها طرق 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، استخدِم مكوّن Issue Tracker المتاح للجميع في Maps Grounding Lite:

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