Maps Tools Resolution API

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

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

إمكانية	طريقة REST	أداة بروتوكول سياق النموذج (MCP)
تحويل أسماء المواقع الجغرافية أو العناوين إلى أماكن	resolveNames	resolve_names
تحويل عناوين URL في "خرائط Google" إلى أماكن	resolveMapsUrls	resolve_maps_urls

قبل البدء

لاستخدام 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.
   • المفتاح هو الفهرس المستند إلى الصفر للعنصر الذي تعذّر إرساله (يتم تمثيله كسلسلة في JSON).
   • القيمة هي عنصر google.rpc.Status يحتوي على رمز الخطأ ورسالة توضّح سبب تعذُّر معالجة السلعة.
4. saveToMapsUrl يغطي النجاحات فقط: يتضمن الرابط saveToMapsUrl العناصر التي تم حلها فقط. ولا يتم تضمين العناصر التي تعذّر نقلها.

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

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

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

الطريقة	السبب	الرمز	رسالة
ResolveNames	لا يمكن مطابقة الاسم أو العنوان مع مكان.	5 ‏(NOT_FOUND)	Place not found.
ResolveMapsUrls	لا يمكن حلّ عنوان URL إلى مكان.	3 ‏(INVALID_ARGUMENT)	Failed to resolve Maps URL to a place.
كلا الطريقتَين	حدث خطأ داخلي أثناء حلّ المشكلة في العنصر.	13 ‏(INTERNAL)	Internal server error. Please retry. If the problem persists, please open a support case. https://goo.gle/maps-platform-support

إعادة محاولة إرسال العناصر التي تعذّر إرسالها فقط باستخدام 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

ملاحظة: إذا بدأت في استخدام Resolution API خلال مرحلتها التجريبية، ستستمر نقاط نهاية v1alpha في العمل. ننصحك بنقل البيانات إلى نقاط النهاية v1.

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:

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