API تفکیک‌پذیری ابزارهای نقشه (آزمایشی)

API مربوط به ابزارهای نقشه‌برداری، نقاط پایانی پردازش دسته‌ای را برای تبدیل نام‌ها و URLهای مکان‌ها به شناسه‌های مکان گوگل مپ فراهم می‌کند.

دسترسی و احراز هویت API

آزمایشی: رابط‌های برنامه‌نویسی کاربردی (API) ResolveNames و ResolveMapsUrls در مرحله آزمایشی (قبل از GA) هستند. محصولات و ویژگی‌های قبل از GA ممکن است پشتیبانی محدودی داشته باشند و تغییرات در محصولات و ویژگی‌های قبل از GA ممکن است با سایر نسخه‌های قبل از GA سازگار نباشد. پیشنهادات قبل از GA تحت پوشش شرایط خاص سرویس پلتفرم نقشه‌های گوگل هستند. برای اطلاعات بیشتر، به توضیحات مرحله راه‌اندازی مراجعه کنید. استفاده از ResolveNames و ResolveMapsUrls در حالی که در مرحله آزمایشی هستند، هیچ هزینه‌ای ندارد.

روش‌های احراز هویت

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

۱. کلید API

شما می‌توانید درخواست‌ها را با افزودن یک کلید API معتبر پلتفرم نقشه‌های گوگل به URL درخواست یا در هدر X-Goog-Api-Key تأیید اعتبار کنید:

https://mapstools.googleapis.com/v1alpha:resolveNames?key=YOUR_API_KEY

۲. محدوده‌های OAuth 2.0

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

• https://www.googleapis.com/auth/maps-platform.mapstools (توصیه شده)

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

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

• محدودیت اندازه دسته : هر دو API حداکثر 20 مورد را در هر درخواست مجاز می‌دانند.
• الزامات ResolveNames :
  • هر آیتم کوئری باید یک پارامتر متنی غیر خالی را مشخص کند.
  • جستجوها باید نشان‌دهنده نام یا آدرس مکان خاصی باشند (مثلاً «Googleplex، Mountain View، CA»، «Eiffel Tower، Paris»).
  • جستجوهای دسته‌بندی‌شده‌ی عمومی (مثلاً «رستوران‌های نیویورک») یا نام‌های زنجیره‌ای عمومی بدون مکان (مثلاً «استارباکس») پشتیبانی نمی‌شوند و ممکن است در حل مشکل با شکست مواجه شوند.
• الزامات ResolveMapsUrls :
  • هر URL باید یک URL معتبر از نظر ساختاری برای نقشه‌های گوگل باشد.
  • فرمت‌های پشتیبانی‌شده عبارتند از:
    • آدرس اینترنتی استاندارد مکان: https://www.google.com/maps/place/...
    • آدرس کوتاه شده: https://maps.app.goo.gl/...
  • آدرس‌های اینترنتی نقشه‌های مبتنی بر جستجوی عمومی (مثلاً https://maps.google.com/?q=restaurant ) و آدرس‌هایی که به یک مکان منحصر به فرد اشاره نمی‌کنند، پشتیبانی نمی‌شوند .

مدیریت خطاهای جزئی

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

چگونه پاسخ را تفسیر کنیم

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

شکست‌های سطح بالا

یک خطای HTTP سطح بالا (مثلاً 400 Bad Request ) فقط در صورتی برگردانده می‌شود که درخواست اعتبارسنجی نشود (مثلاً هنگام ارسال بیش از 20 مورد یا عدم وجود فیلدهای الزامی).

مشخصات API و مثال‌های Curl

۱. رابط برنامه‌نویسی کاربردی ResolveNames

روش: پست

https://mapstools.googleapis.com/v1alpha:resolveNames

قالب بدنه درخواست

{
  "queries": [
    { "text": "string" }
  ],
  "locationBias": {
    "viewport": {
      "low": { "latitude": number, "longitude": number },
      "high": { "latitude": number, "longitude": number }
    }
  },
  "regionCode": "string"
}

• queries (الزامی): فهرست تکراری پرس‌وجوها برای حل (حداکثر 20).
• locationBias (اختیاری): کادر محدودکننده‌ی نمای دید (viewport) برای جهت‌دهی نتایج به سمت یک ناحیه‌ی محلی.
• regionCode (اختیاری): کد کشور CLDR (مثلاً "US"، "FR") برای اعمال تغییرات در نتایج.

مثال Curl: حل موفقیت‌آمیز

این کوئری «Googleplex» و «Eiffel Tower» را حل می‌کند.

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "Googleplex, Mountain View, CA" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveNames?key=KEY"

پاسخ JSON

{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ]
}

مثال 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/v1alpha:resolveNames?key=KEY"

پاسخ JSON

{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  }
}

۲. رابط برنامه‌نویسی کاربردی ResolveMapsUrls

روش: پست

https://mapstools.googleapis.com/v1alpha:resolveMapsUrls

قالب بدنه درخواست

{
  "urls": [
    "string"
  ]
}

• urls (الزامی): فهرست تکراری رشته‌های آدرس اینترنتی نقشه‌های گوگل برای حل (حداکثر ۲۰ عدد).

مثال 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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"

پاسخ JSON

{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    }
  ]
}

مثال 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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"

پاسخ JSON

{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Invalid URL."
    }
  }
}

مثال 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/v1alpha:resolveMapsUrls?key=KEY"

پاسخ JSON

{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}