Maps Tools Resolution API

‫Maps Tools Resolution API بخشی از Maps Grounding Lite است. این میانای برنامه‌سازی کاربردی نقاط پایانی دسته‌ای ارائه می‌دهد که نام مکان‌ها و نشانی‌های وب Google Maps را به شناسه‌های مکان Google Maps تبدیل می‌کند. می‌توانید از «شناسه‌های جا» برگردانده‌شده با دیگر میاناهای برنامه‌سازی کاربردی Google Maps Platform استفاده کنید. هر پاسخ همچنین شامل پیوندی است که مکان‌های حل‌شده را به‌عنوان فهرستی در Google Maps ذخیره می‌کند.

Resolution API هم به‌صورت روش‌های REST و هم به‌صورت ابزار در سرور Maps Grounding Lite MCP دردسترس است:

قابلیت روش REST ابزار MCP
تبدیل نام یا نشانی مکان‌ها به مکان resolveNames resolve_names
تبدیل نشانی‌های وب Google Maps به مکان‌ها resolveMapsUrls resolve_maps_urls

قبل‌از شروع

برای استفاده از Resolution API، به پروژه Google Cloud با صورت‌حساب فعال و سرویس Maps Grounding Lite API فعال نیاز دارید. برای دریافت دستورالعمل‌ها، به فعال کردن سرویس Maps Grounding Lite در پروژه Google Cloud مراجعه کنید.

دسترسی و اصالت‌سنجی میانای برنامه‌سازی کاربردی

Resolution API از هر دو اعتبارنامه کلید میانای برنامه‌سازی کاربردی و OAuth 2.0 پشتیبانی می‌کند.

کلید میانای API

می‌توانید با ارسال کلید میانای برنامه‌سازی کاربردی معتبر Google Maps Platform در سرصفحه X-Goog-Api-Key یا با افزودن آن به نشانی وب درخواست، درخواست‌ها را اصالت‌سنجی کنید:

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

در مثال‌های این صفحه، API_KEY را با کلید میانای API خودتان جایگزین کنید.

دامنه‌های OAuth 2.0

اگر از مجوز OAuth استفاده می‌کنید، دامنه زیر پشتیبانی می‌شود:

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

حدود استفاده

سهمیه‌های پیش‌فرض زیر برای Resolution API اعمال می‌شود:

  • ResolveNames: ‏۶۰۰ پُرسمان در دقیقه، به‌ازای هر پروژه.
  • ResolveMapsUrls: ‏۶۰۰ پُرسمان در دقیقه، برای هر پروژه.
  • اندازه دسته: حداکثر ۲۰ پُرسمان یا نشانی وب در هر درخواست.

هر درخواست، صرف‌نظر از تعداد موارد موجود در آن، به‌عنوان یک پُرسمان محسوب می‌شود.

قیمت‌گذاری

درخواست‌های ارسال‌شده به ResolveNames و ResolveMapsUrls بدون هزینه (۰ دلار) تحت شناسه واحد کالا Places API Text Search Essentials (IDs Only) صورت‌حساب می‌شوند. مانند بقیه Maps Grounding Lite، پروژه شما باید حساب صورت‌حساب داشته باشد.

اعتبارسنجی و محدودیت‌های درخواست

برای جلوگیری از بارگذاری بیش‌ازحد و اطمینان از زمان پاسخ سریع، درخواست‌های دسته‌ای به‌طور دقیق اعتبارسنجی می‌شوند:

  • محدودیت اندازه دسته: هر دو روش حداکثر ۲۰ مورد را برای هر درخواست مجاز می‌دانند.
  • الزامات ResolveNames:
    • هر مورد در queries باید پارامتر text غیرخالی را مشخص کند.
    • پرسمان‌ها باید نشان‌دهنده نام یا نشانی مکان خاصی باشند (برای مثال، «Googleplex, Mountain View, CA» یا «Eiffel Tower, Paris»).
    • جستجوهای دسته‌ای عمومی (برای مثال، «رستوران‌های نیویورک») یا نام‌های زنجیره‌ای عمومی بدون مکان (برای مثال، «استارباکس») پشتیبانی نمی‌شوند و ممکن است حل نشوند.
  • الزامات ResolveMapsUrls:
    • هر نشانی وب باید ازنظر ساختاری نشانی وب معتبر Google Maps باشد.
    • قالب‌های پشتیبانی‌شده شامل موارد زیر است:
      • نشانی وب مکان استاندارد: https://www.google.com/maps/place/...
      • نشانی وب کوتاه: https://maps.app.goo.gl/...
    • نشانی‌های وب Maps مبتنی بر پُرسمان عمومی (برای مثال، https://maps.google.com/?q=restaurant) و نشانی‌های وب که به یک مکان منحصربه‌فرد اشاره نمی‌کنند پشتیبانی نمی‌شوند.

ذخیره کردن مکان‌های حل‌شده در Google Maps

اگر حداقل یک مورد در دسته حل شود، پاسخ شامل فیلد saveToMapsUrl است. این یک پیوند Google Maps است که شامل همه مکان‌های با موفقیت حل‌شده در دسته است. این پیوند را به کاربرانی ارائه دهید که می‌خواهند جاهای حل‌شده را به‌عنوان فهرستی در Google Maps ذخیره، هم‌رسانی، یا باز کنند.

همیشه از پیوند برگردانده‌شده توسط میانای برنامه‌سازی کاربردی استفاده کنید. خودتان پیوند را نسازید. اگر هیچ موردی در دسته حل نشود، پاسخ شامل saveToMapsUrl نخواهد بود.

رسیدگی به خطاهای جزئی

هر دو روش پردازشگر دسته‌ای هستند. اگر برخی‌از موارد در یک دسته حل نشوند، کل درخواست با خطای سطح بالا مواجه نمی‌شود. درعوض، API پاسخ موفقیت جزئی برمی‌گرداند و باید پاسخ را برای خطاهای هر مورد بررسی کنید.

تفسیر پاسخ

  1. تضمین هم‌ترازی ۱:۱: فهرست results برگردانده‌شده (برای ResolveNames) یا فهرست entities (برای ResolveMapsUrls) با فهرست ورودی، براساس نمایه، ۱:۱ نگاشت می‌شود.
  2. عناصر خالی برای موارد ناموفق: اگر مورد در نمایه i حل نشد، فهرست نتایج حاوی شیء خالی {} در نمایه i است.
  3. نقشه failedRequests: پاسخ حاوی نقشه failedRequests است.
    • کلید، نمایه مبتنی بر ۰ مورد ناموفق است (که به‌صورت رشته در JSON نشان داده می‌شود).
    • مقدار یک شیء google.rpc.Status است که حاوی کد خطا و پیامی است که توضیح می‌دهد چرا مورد ناموفق بوده است.
  4. saveToMapsUrl فقط موارد موفق را پوشش می‌دهد: پیوند saveToMapsUrl فقط شامل مواردی است که حل‌وفصل شده‌اند. موارد ناموفق اضافه نشده‌اند.

فرض نکنید که کل دسته ناموفق بوده است چون یک مورد ناموفق بوده است. همیشه failedRequests را بررسی کنید تا ببینید کدام موارد، درصورت وجود، حل‌وفصل نشده‌اند.

خطاهای هر مورد

جدول زیر خطاهای مربوط به هر مورد را که ممکن است در failedRequests ببینید فهرست می‌کند:

روش علت کد پیام
ResolveNames نام یا نشانی نمی‌تواند به مکان تبدیل شود. ‫5‏ (NOT_FOUND) Place not found.
ResolveMapsUrls نشانی وب نمی‌تواند به مکان تبدیل شود. ‫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 ناموفق بوده‌اند دوباره امتحان کنید.

خطاهای سطح بالا

در موارد زیر، API به‌جای پاسخ جزئی، خطای سطح بالا برمی‌گرداند:

  • درخواست نامعتبر (400 INVALID_ARGUMENT): درخواست حاوی بیش‌از ۲۰ مورد است، درخواست ResolveNames فاقد پُرسمان است یا پُرسمانی با مقدار text خالی دارد، یا درخواست ResolveMapsUrls نشانی وبی دارد که خالی است یا ازنظر نحوی نشانی وب معتبری نیست. یک مورد نامعتبر باعث می‌شود کل درخواست ناموفق شود.
  • خطاهای اصالت‌سنجی، اجازه، یا سهمیه: برای مثال، کلید API وجود ندارد یا نامعتبر است، یا درخواست از محدودیت‌های استفاده فراتر می‌رود.
  • خطاهای سرور (500 INTERNAL): درخواست را دوباره امتحان کنید.

استفاده از Resolution API با MCP

سرور Maps Grounding Lite MCP در https://mapstools.googleapis.com/mcp Resolution API را به‌عنوان دو ابزار نشان می‌دهد:

  • resolve_names: دسته‌ای از نام‌ها یا نشانی‌های مکان را به «شناسه جا» تبدیل می‌کند.
  • resolve_maps_urls: دسته‌ای از نشانی‌های وب Google Maps را به «شناسه‌های مکان» تبدیل می‌کند.

وقتی مدل زبانی بزرگ خود را برای استفاده از سرور Maps Grounding Lite MCP پیکربندی می‌کنید، این ابزارها در کنار سایر ابزارهای Maps Grounding Lite دردسترس هستند. این ابزارها همان ورودی‌ها را می‌پذیرند، همان محدودیت‌ها را اعمال می‌کنند، و همان پاسخ خطای جزئی را مانند روش‌های REST برمی‌گردانند.

پاسخ‌های ابزار شامل فیلد save_to_maps_url است. توضیحات ابزار به «مدل زبانی بزرگ» دستور می‌دهد که وقتی کاربر می‌خواهد مکان‌های حل‌شده را به‌عنوان فهرستی در Google Maps ذخیره، هم‌رسانی، یا باز کند، این پیوند را ارائه دهد، به‌جای اینکه خودش پیوندی بسازد.

مثال زیر از 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 (الزامی): فهرست تکراری پُرسمان‌ها برای حل کردن (حداکثر ۲۰).
  • 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 (الزامی): فهرست تکراری رشته‌های نشانی وب Google Maps برای حل کردن (حداکثر ۲۰).

نمونه Curl: حل‌وفصل موفقیت‌آمیز

نمونه زیر نشانی وب مکان استاندارد Google Maps را حل می‌کند:

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: نتایج مختلط (شکست جزئی)

مثال زیر یک نشانی وب مکان معتبر و یک نشانی وب را که نمی‌تواند به مکان حل شود، حل می‌کند:

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: ناموفق بودن اعتبارسنجی

مثال زیر بیش‌از ۲۰ نشانی وب را در یک درخواست ارسال می‌کند:

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 استفاده کنید: