Maps Tools Resolution API

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

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

إمكانية	طريقة 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 (المعرّفات فقط). كما هو الحال مع بقية Maps Grounding Lite، يجب أن يتضمّن مشروعك حساب فوترة.

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

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

• الحد الأقصى لحجم المجموعة: يسمح كلا الإجرائين بإضافة 20 عنصرًا كحد أقصى لكل طلب.
• متطلبات ResolveNames:
  • يجب أن يحدّد كل عنصر في queries المَعلمة text غير الفارغة.
  • يجب أن تمثّل طلبات البحث اسم مكان أو عنوانًا محدّدًا (على سبيل المثال، "Googleplex، ماونتن فيو، كاليفورنيا" أو "برج إيفل، باريس").
  • لا تتوافق الطلبات العامة المتعلقة بفئات معيّنة (مثل "مطاعم في القاهرة") أو أسماء السلاسل العامة بدون موقع جغرافي (مثل "ستاربكس") مع هذه الميزة وقد لا يتم حلّها.
• متطلبات ResolveMapsUrls:
  • يجب أن يكون كل عنوان URL صالحًا من الناحية البنيوية على "خرائط Google".
  • تشمل التنسيقات المتوافقة ما يلي:
    • عنوان URL العادي للمكان: https://www.google.com/maps/place/...
    • عنوان URL مختصر: https://maps.app.goo.gl/...
  • لا يمكن استخدام عناوين URL العامة المستندة إلى طلب البحث (مثل 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:

الطريقة	السبب	الرمز	رسالة
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 فارغًا أو غير صالح من الناحية النحوية. يؤدي عنصر واحد غير صالح إلى تعذُّر تلبية الطلب بأكمله.
• أخطاء في المصادقة أو الأذونات أو الحصة: على سبيل المثال، مفتاح واجهة برمجة التطبيقات غير متوفّر أو غير صالح، أو يتجاوز الطلب حدود الاستخدام.
• أخطاء الخادم (500 INTERNAL): أعِد محاولة الطلب.

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

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

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

عند ضبط نموذج اللغة الكبير (LLM) لاستخدام خادم MCP الخاص بأداة Maps Grounding Lite، ستتوفّر هذه الأدوات إلى جانب أدوات 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:

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