Maps Tools Resolution API

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

«میانای برنامه‌سازی کاربردی وضوح» هم به‌عنوان روش‌های REST و هم به‌عنوان ابزارهایی در سرور Maps Grounding Lite MCP دردسترس است:

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

قبل‌از شروع

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

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

«میانای برنامه‌سازی کاربردی وضوح» از هر دو اعتبارنامه کلید میانای برنامه‌سازی کاربردی و OAuth 2.0 پشتیبانی می‌کند.

کلید میانای API

می‌توانید درخواست‌ها را با ارسال کلید معتبر «میانای برنامه‌سازی کاربردی پلاتفرم Google Maps» در سرایند 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

حدود استفاده

سهمیه‌های پیش‌فرض زیر برای «میانای برنامه‌سازی کاربردی وضوح» اعمال می‌شود:

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

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

قیمت‌گذاری

درخواست‌های ResolveNames و ResolveMapsUrls تحت واحد نگهداری کالا Places API Text Search Essentials (فقط شناسه‌ها) بدون هزینه ($۰) صورت‌حساب می‌شود. مانند بقیه «پروژه زمین‌گذاری Maps 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 ناموفق بودند دوباره امتحان کنید.

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

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

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

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

سرور Maps Grounding Lite MCP در https://mapstools.googleapis.com/mcp «میانای برنامه‌سازی کاربردی وضوح» را به‌عنوان دو ابزار نمایان می‌کند:

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

وقتی «مدل زبانی بزرگ» خود را برای استفاده از سرور MCP «Maps Grounding Lite» پیکربندی می‌کنید، این ابزارها درکنار دیگر ابزارهای «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

توجه: اگر در مرحله «آزمایشی» استفاده از «میانای برنامه‌سازی کاربردی وضوح» را شروع کرده‌اید، نقطه‌های پایانی 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 (الزامی): فهرست تکراری پُرسمان‌ها برای حل کردن (حداکثر ۲۰).
• 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"
  }
}

ارسال بازخورد

برای گزارش مشکل یا هم‌رسانی بازخورد درباره «میانای برنامه‌سازی کاربردی وضوح»، از عنصر عمومی Maps Grounding Lite در Issue Tracker استفاده کنید:

• گزارش اشکال
• ارسال درخواست ویژگی
• ارسال بازخورد