MCP Tools Reference: mapstools.googleapis.com

ابزار: resolve_names

فهرست دسته‌ای از درخواست‌های مکان‌های خاص (نام‌های برجسته یا آدرس‌های دقیق) را به شناسه‌های مکان متعارف نقشه‌های گوگل تبدیل می‌کند.

الزامات ورودی (بحرانی):

  1. queries (آرایه‌ای از اشیاء - اجباری): فهرستی از پرس‌وجوهای مکانی برای حل کردن. می‌توانید تا 20 پرس‌وجو مشخص کنید.

    • هر شیء پرس و جو باید دارای موارد زیر باشد:
      • text (رشته - اجباری): عبارت جستجوی متنی که نام یا آدرس مکان خاصی را برای حل نشان می‌دهد.
        • مثال‌ها: 'Googleplex, Mountain View, CA' ، '1600 Amphitheatre Pkwy, Mountain View, CA' ، 'Eiffel Tower, Paris' .

  2. location_bias (object - اختیاری): از این برای اولویت‌بندی نتایج نزدیک به یک منطقه جغرافیایی خاص استفاده کنید.

    • قالب: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

  3. region_code (رشته - اختیاری): کد منطقه یونیکد CLDR (کد کشور دو حرفی، مثلاً US ، CA ) کاربر برای اعمال سوگیری در نتایج.

دستورالعمل فراخوانی ابزار:

  • ویژگی (بحرانی): جستجوها باید نشان‌دهنده نام یا آدرس مکان خاصی باشند. جستجوهای عمومی مانند 'restaurants' یا نام‌های زنجیره‌ای مانند 'Starbucks' پشتیبانی نمی‌شوند.
  • اگر ابزارهای پایین‌دستی که قصد فراخوانی آنها را دارید، از قبل رشته‌های خام آدرس یا نام مکان را مستقیماً می‌پذیرند، این ابزار را فراخوانی نکنید.

مدیریت خطا (بحرانی):

  • این یک ابزار پردازش دسته‌ای است. یک درخواست ممکن است "نتایج مختلط" را برگرداند (مثلاً برخی از پرس‌وجوها با موفقیت حل می‌شوند در حالی که برخی دیگر شکست می‌خورند).
  • تضمین می‌شود که فهرست خروجی results با اندیس‌های queries ورودی به صورت ۱:۱ نگاشت شود. یک پرس‌وجوی ناموفق منجر به نمایش یک پیام Result خالی (هیچ entity تنظیم نشده است) در اندیس مربوطه در فهرست results خواهد شد.
  • شما باید فیلد نگاشت failed_requests را در پاسخ بررسی کنید تا مشخص شود کدام اندیس پرس‌وجوی خاص ناموفق بوده است. کلید failed_requests نشان دهنده اندیس مبتنی بر 0 پرس‌وجوی ناموفق در درخواست است. فرض نکنید که کل فراخوانی دسته‌ای به دلیل یک شکست جزئی ناموفق بوده است.

نمونه زیر نحوه استفاده از curl برای فراخوانی ابزار resolve_names MCP را نشان می‌دهد.

درخواست کرل 
                  
curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_names",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

طرحواره ورودی

درخواست پیام برای ResolveNames.

درخواست حل نام‌ها

نمایش JSON 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
فیلدها
queries[]

object ( LocationQuery )

الزامی. فهرستی از درخواست‌های مکانی که باید حل شوند. می‌توانید تا ۲۰ درخواست را مشخص کنید.

locationBias

object ( LocationBias )

اختیاری. یک ناحیه اختیاری برای بایاس کردن نتایج تفکیک. در صورت مشخص شدن، نتایج تفکیک به سمت موجودیت‌هایی که به این ناحیه نزدیک‌تر هستند بایاس می‌شوند. گنجاندن location_bias یا region_code اغلب با محدود کردن فضای جستجو، نتایج بهتری ارائه می‌دهد.

اگر هر دو location_bias و region_code مشخص شده باشند، location_bias بر region_code اولویت دارد.

regionCode

string

اختیاری. یک کد منطقه اختیاری برای سوگیری نتایج تفکیک. در صورت مشخص شدن، نتایج تفکیک به سمت موجودیت‌هایی که در منطقه مشخص شده یا نزدیک آن هستند، سوگیری خواهد شد. این باید یک کد منطقه CLDR باشد. به عنوان مثال، "US" یا "CA". گنجاندن location_bias یا region_code اغلب با محدود کردن فضای جستجو، نتایج بهتری ارائه می‌دهد.

اگر هر دو location_bias و region_code مشخص شده باشند، location_bias بر region_code اولویت دارد.

جستجوی موقعیت مکانی

نمایش JSON 
{
  "text": string
}
فیلدها
text

string

الزامی. عبارت جستجوی متنی برای رسیدن به یک موجودیت مکانی خاص در نقشه‌های گوگل، مانند یک مکان یا یک آدرس. هرچه عبارت جستجو خاص‌تر باشد، وضوح آن دقیق‌تر است. برای مثال، "سانفرانسیسکو"، "گوگل‌پلکس، مانتین ویو، کالیفرنیا"، "1600 آمفی‌تئاتر پارک‌وی، مانتین ویو، کالیفرنیا" یا "برج ایفل، پاریس". عبارت‌های جستجو باید شامل یک آدرس یا نام مکان خاص باشند. مکان‌های عمومی مانند نام یک فروشگاه زنجیره‌ای (مثلاً استارباکس) یا عبارت جستجویی مانند "رستوران‌ها" پشتیبانی نمی‌شوند.

موقعیت مکانی

نمایش JSON 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
فیلدها
type فیلد Union. نوع بایاس مکانی. type می‌تواند فقط یکی از موارد زیر باشد:
viewport

object ( Viewport )

یک دریچه دید که توسط یک کادر محصورکننده تعریف می‌شود.

ویوپورت

نمایش JSON 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
فیلدها
low

object ( LatLng )

الزامی. نقطه پایین دید.

high

object ( LatLng )

الزامی. نقطه اوج منظره.

لات‌لنگ

نمایش JSON 
{
  "latitude": number,
  "longitude": number
}
فیلدها
latitude

number

عرض جغرافیایی بر حسب درجه. باید در محدوده [-90.0، +90.0] باشد.

longitude

number

طول جغرافیایی بر حسب درجه. باید در محدوده [-۱۸۰.۰، +۱۸۰.۰] باشد.

طرحواره خروجی

پیام پاسخ برای ResolveNames.

پاسخ ResolveNames

نمایش JSON 
{
  "results": [
    {
      object (Result)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  }
}
فیلدها
results[]

object ( Result )

فقط خروجی. فهرست موجودیت‌های حل‌شده از کوئری‌های مکان. تضمین می‌شود که با اندیس‌های queries درخواست، به صورت ۱:۱ نگاشت شود. یک رشته خالی در اندیس i نشان می‌دهد که حل آن کوئری با شکست مواجه شده است. اگر حل آن با شکست مواجه شد، لطفاً فیلد failed_requests را برای وضعیت خطا بررسی کنید.

failedRequests

map (key: integer, value: object ( Status ))

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

یک شیء شامل لیستی از جفت‌های "key": value . مثال: { "name": "wrench", "mass": "1.3kg", "count": "3" } .

نتیجه

نمایش JSON 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
فیلدها
entity

object ( Entity )

فقط خروجی. موجودیت حل شده از جستجوی مکان.

confidence

enum ( Confidence )

فقط خروجی. سطح اطمینان برای حل.

نهاد

نمایش JSON 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
فیلدها
entity فیلد Union. نوع موجودیت حل شده. entity می‌تواند فقط یکی از موارد زیر باشد:
place

string

نام منبع مکان حل‌شده.

ورود درخواست‌های ناموفق

نمایش JSON 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
فیلدها
key

integer

value

object ( Status )

وضعیت

نمایش JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
فیلدها
code

integer

کد وضعیت، که باید یک مقدار شمارشی از google.rpc.Code باشد.

message

string

یک پیام خطای مربوط به توسعه‌دهنده که باید به زبان انگلیسی باشد. هرگونه پیام خطای مربوط به کاربر باید بومی‌سازی شده و در فیلد google.rpc.Status.details ارسال شود، یا توسط کلاینت بومی‌سازی شود.

details[]

object

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

یک شیء حاوی فیلدهایی از نوع دلخواه. یک فیلد اضافی "@type" حاوی یک URI است که نوع را مشخص می‌کند. مثال: { "id": 1234, "@type": "types.example.com/standard/id" } .

هر

نمایش JSON 
{
  "typeUrl": string,
  "value": string
}
فیلدها
typeUrl

string

نوع پیام سریالی شده Protobuf را با یک مرجع URI متشکل از پیشوندی که به یک اسلش ختم می‌شود و نام نوع کاملاً واجد شرایط، مشخص می‌کند.

مثال: type.googleapis.com/google.protobuf.StringValue

این رشته باید حداقل شامل یک کاراکتر / باشد و محتوای بعد از آخرین / باید نام کامل نوع به شکل متعارف و بدون نقطه باشد. روی این ارجاعات URI طرحی ننویسید تا کلاینت‌ها نتوانند با آنها تماس بگیرند.

این پیشوند دلخواه است و انتظار می‌رود پیاده‌سازی‌های Protobuf به سادگی همه چیز را تا آخرین / برای شناسایی نوع حذف کنند. type.googleapis.com/ یک پیشوند پیش‌فرض رایج است که برخی از پیاده‌سازی‌های قدیمی به آن نیاز دارند. این پیشوند منشأ نوع را نشان نمی‌دهد و انتظار نمی‌رود URI های حاوی آن به هیچ درخواستی پاسخ دهند.

تمام رشته‌های نوع URL باید ارجاعات URI قانونی باشند، با این محدودیت اضافی (برای قالب متن) که محتوای ارجاع باید فقط شامل کاراکترهای حرفی-عددی، کاراکترهای escape با کدگذاری درصد و کاراکترهای موجود در مجموعه زیر (بدون احتساب علامت‌های برگشتی بیرونی) باشد: /-.~_!$&()*+,;= . با وجود اینکه کدگذاری‌های درصد را مجاز می‌دانیم، پیاده‌سازی‌ها نباید آنها را unscape کنند تا از سردرگمی با تجزیه‌کننده‌های موجود جلوگیری شود. به عنوان مثال، type.googleapis.com%2FFoo باید رد شود.

در طراحی اولیه Any ، امکان راه‌اندازی سرویس تشخیص نوع در این نوع URLها در نظر گرفته شده بود، اما Protobuf هرگز آن را پیاده‌سازی نکرد و تماس با این URLها را مشکل‌ساز و یک مسئله امنیتی بالقوه می‌داند. سعی نکنید با URLهای نوع تماس بگیرید.

value

string ( bytes format)

یک سریال‌سازی Protobuf از نوع توصیف‌شده توسط type_url را نگه می‌دارد.

یک رشته کدگذاری شده با base64.

اعتماد به نفس

سطح اطمینان برای قطعنامه.

انوم‌ها
CONFIDENCE_UNSPECIFIED مقدار پیش‌فرض. این مقدار استفاده نشده است.
MEDIUM اطمینان متوسط ​​نشان می‌دهد که این راه‌حل احتمالاً درست است، اما ممکن است گزینه‌های دیگری نیز وجود داشته باشد.
HIGH اطمینان بالا نشان می‌دهد که تفکیک‌پذیری صحیح است و یک موجودیت جغرافیایی-مکانی خاص (مثلاً یک مکان خاص) را نشان می‌دهد.

حاشیه‌نویسی ابزار

راهنمایی مخرب: ❌ | راهنمایی بی‌اثر: ❌ | راهنمایی فقط خواندنی: ✅ | راهنمایی جهان باز: ❌