با استفاده از URL Maps یا Places API، کاربران را به جزئیات و مسیرهای مکان‌ها در نقشه‌های Google هدایت کنید

در دنیای امروزی که از موقعیت مکانی آگاه است، کاربران انتظار دسترسی یکپارچه به اطلاعات مکان، مسیرها و ناوبری را دارند. خواه از طریق یک برنامه پیام رسان، یک برنامه کشف زمینه محلی، یک پلت فرم تدارکات و حمل و نقل، یک برنامه ریز سفر، یا یک پلت فرم لیست املاک باشد، کاربران اغلب نیاز دارند جزئیات مکان را به سرعت مشاهده کنند یا بهترین مسیر را از A به B پیدا کنند. در حالی که توسعه دهندگان می توانند تجربه درون برنامه ای خود را ایجاد کنند، استفاده از رابط جامع و آشنای Google Maps تجربه برتری را ارائه می دهد.

یک URL نقشه گوگل با ساختار مناسب برای یک تجربه کاربری یکپارچه ضروری است. نشانی‌های اینترنتی نادرست این تجربه را به خطر می‌اندازد، کاربران را به مکان اشتباه هدایت می‌کند، به جای جزئیات خاص، نمای کلی نقشه را نشان می‌دهد، یا حتی منجر به ایجاد یک لینک شکسته می‌شود. این باعث ناامیدی کاربران می شود و آنها را از دستیابی به هدفشان باز می دارد. به عنوان مثال، حتی با یک نشانی وب Maps معتبر، کاربری که منتظر جزئیات یک کسب و کار خاص است، ممکن است درعوض بر روی نمای کلی نقشه بدون اطلاعات مرتبط قرار بگیرد. مثال زیر را ببینید:

https://www.google.com/maps/search/?api=1&query=-33.8567%2C151.2152

این URL Maps برای باز کردن Google Maps و نمایش یک مکان بر اساس طول و عرض جغرافیایی معتبر است. با این حال جزئیات مربوط به مکان خاصی را در اختیار کاربران قرار نمی دهد.

جستجو فقط با استفاده از طول و عرض جغرافیایی

پل زدن یکپارچه برنامه خود با نقشه های گوگل از طریق URL های دقیق

URL Maps با نام مکان منحصر به فرد، کاربران را به صفحه جزئیات آن مکان در Google Maps هدایت می کند

پلتفرم نقشه های گوگل (GMP) دو روش اصلی برای ساخت URL های دقیق ارائه می دهد: Places API (جدید) که به کلید API نیاز دارد و URL های Maps که رایگان هستند و به کلید نیاز ندارند. راه حل های زیر به سناریوهای مختلف و موارد استفاده می پردازند:

استفاده از قسمت googleMapsUri یا googleMapsLinks در GMP Places API(New)

GMP Places API (جدید) مجموعه ای جامع از اطلاعات در مورد یک مکان خاص را برمی گرداند. هنگام درخواست فیلد googleMapsUri یا googleMapsLinks (با مشخص کردن آن در فیلد ماسک )، پاسخ API شامل یک شی مکان است. این شی حاوی URL های از پیش قالب بندی شده است که می توان از آنها برای باز کردن مستقیم نمای مربوطه، مانند نمای جزئیات مکان، در Google Maps استفاده کرد.

مثال:

درخواست جزئیات مکان

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: YOUR_API_KEY" \
-H "X-Goog-FieldMask: googleMapsUri,googleMapsLinks" \
https://places.googleapis.com/v1/places/ChIJ3S-JXmauEmsRUcIaWtf4MzE

پاسخ جزئیات مکان:

{
    "googleMapsUri": "https://maps.google.com/?cid=3545450935484072529",
    "googleMapsLinks": {
        "directionsUri": "https://www.google.com/maps/dir//''/data=!4m7!4m6!1m1!4e2!1m2!1m1!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!3e0",
        "placeUri": "https://maps.google.com/?cid=3545450935484072529",
        "writeAReviewUri": "https://www.google.com/maps/place//data=!4m3!3m2!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!12e1",
        "reviewsUri": "https://www.google.com/maps/place//data=!4m4!3m3!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!9m1!1b1",
        "photosUri": "https://www.google.com/maps/place//data=!4m3!3m2!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!10e5"
    }
}

ChIJ3S-JXmauEmsRUcIaWtf4MzE در مثال بالا شناسه مکان اپرای سیدنی در مثال بالا است. شناسه مکان یک شناسه متنی است که مکان را در پایگاه داده Google Places و در Google Maps به طور منحصر به فرد شناسایی می کند.

بازیابی شناسه مکان با هزینه صفر

برای بازیابی برنامه‌نویسی شناسه‌های مکان، می‌توانید از عملکرد Places API: جستجوی متن (فقط شناسه) استفاده کنید. این یک روش هزینه صفر برای دریافت شناسه مکان است. درباره Place ID و درخواست Place API (جدید) بیشتر بیاموزید.

درخواست جستجوی متنی Places API (فقط شناسه):

curl -X POST -d '{"textQuery" : "Sydney Opera House"}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: places.id' \
'https://places.googleapis.com/v1/places:searchText'

پاسخ جستجوی متن API Places (فقط شناسه):

{
  "places": [
    {
      "id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
    }
  ]
}

شناسه‌های مکان همچنین می‌توانند زمانی که کاربر روی یک POI روی نقشه کلیک یا ضربه می‌زند، بازیابی شود. جزئیات بیشتر در مورد نمادهای POI قابل کلیک ( جاوا اسکریپت ، اندروید ، iOS ) بیابید

پیاده سازی

هنگام استفاده از Places API، توسعه دهندگان می توانند به سادگی فیلد googleMapsUri یا googleMapsLinks را از پاسخ استخراج کنند و در صورت نصب نشدن برنامه، از آن برای راه اندازی نمای مربوطه در برنامه Google Maps یا در مرورگر استفاده کنند.

ویژگی	توضیحات
جهت هایUri	پیوندی برای باز کردن Google Maps برای نمایش مسیرها از مکان فعلی کاربر به این مکان
placeUri	پیوند باز کردن Google Maps به صفحه جزئیات مکان برای این مکان
writeAReviewUri	پیوند باز کردن Google Maps به صفحه نوشتن نظر برای این مکان
نظرات اوری	پیوند باز کردن Google Maps به صفحه نظرات برای این مکان
عکسهای اوری	پیوند باز کردن Google Maps به صفحه عکس‌های این مکان

راهنمای توسعه‌دهنده را بررسی کنید و این ویژگی را امروز امتحان کنید.

استفاده از URL های Maps

با استفاده از نشانی‌های اینترنتی Maps، می‌توانید یک URL جهانی و چند پلتفرمی برای راه‌اندازی Google Maps و انجام جستجو، دریافت مسیرها و پیمایش، و نمایش نماهای نقشه و تصاویر پانوراما بسازید. دستور URL صرف نظر از پلتفرم مورد استفاده یکسان است. برای استفاده از URL های Maps به کلید API Google نیاز ندارید.

اقدامات نقشه موجود عبارتند از:

• اگر برنامه نصب نشده باشد که یک پین را برای یک مکان خاص نمایش می دهد، یا یک جستجوی کلی انجام می دهد و نقشه ای را برای نمایش نتایج اجرا می کند، عملکرد جستجو یک برنامه Google Maps یا در یک مرورگر راه اندازی می کند.

• اگر برنامه نصب نشده باشد، عملکرد Directions یک برنامه Google Maps یا در یک مرورگر راه‌اندازی می‌کند که مسیرها را بین نقاط نمایش می‌دهد یا ناوبری گام به گام را در Google Maps برای دستگاه‌های تلفن همراه فعال می‌کند.

• عملکرد پانورامای نمای خیابان به شما امکان می دهد یک بیننده را برای نمایش تصاویر نمای خیابان به عنوان پانورامای تعاملی راه اندازی کنید.

برای کاوش توابع و نمونه‌های بیشتر ، از اسناد توسعه‌دهنده نشانی‌های وب نقشه‌های GMP دیدن کنید.

در اینجا ما به دو ویژگی کلیدی URL های Maps می پردازیم:

• نمایش جزئیات مکان در Google Maps: این بخش نحوه ساخت URL هایی را توضیح می دهد که جزئیات یک مکان خاص را در Google Maps نشان می دهد. همچنین نحوه کار با مکان‌هایی که نام‌های غیر منحصر به فرد دارند با استفاده از شناسه‌های مکان و پرس و جوهای دقیق، توضیح می‌دهد.

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

نمایش جزئیات مکان در Google Maps

تابع Search دو پارامتر را برای تکمیل جستجوی مکان ها دریافت می کند که عبارتند از query (الزامی) و query_place_id (اختیاری).

پارامتر query برای همه درخواست های جستجو مورد نیاز است. نام مکان یا مختصات طول و عرض جغرافیایی جدا شده با کاما یا یک عبارت جستجوی کلی را می پذیرد.

ساختار URL جستجو:

https://www.google.com/maps/search/?api=1&parameters

سناریو 1: نمایش جزئیات مکان برای یک نام مکان منحصر به فرد

https://www.google.com/maps/search/?api=1&query=Sydney%20Opera%20House

در این مثال فقط نام مکان مشخص شده است. این URL صفحه جزئیات را برای خانه اپرای سیدنی باز می کند.

جستجوی نام مکان و نمایش جزئیات مکان

اکنون مکانی را با نامی غیر منحصر به فرد در نظر بگیرید. وقتی فقط با این نام غیر منحصر به فرد جستجو می کنید چه اتفاقی می افتد؟ سناریوی بعدی را ببینید.

سناریو 2: مکان ها را برای نام مکان غیر منحصر به فرد جستجو کنید

https://www.google.com/maps/search/?api=1&query=7-Eleven

از آنجایی که نام مکان منحصر به فرد نیست، این نشانی وب فهرستی از مکان های 7-Eleven نزدیک را در درگاه نمایش باز می کند. سپس کاربران می توانند یک فروشگاه خاص را برای مشاهده جزئیات آن انتخاب کنند.

صفحه فهرست مکان برای جستجوی نام غیر منحصر به فرد

برای اجتناب از فهرست مکان ها و دسترسی مستقیم به صفحه جزئیات خاص، می توانید از روش دقیق تری استفاده کنید. مثال بعدی را ببینید.

سناریو 3: نمایش جزئیات مکان برای نام مکان غیر منحصر به فرد

هنگامی که با نام مکان های رایج سروکار دارید، یک جستجوی ساده نام اغلب فهرستی از مکان ها را نشان می دهد. برای پیوند مستقیم به یک صفحه جزئیات خاص، می توانید از یکی از روش های زیر استفاده کنید:

روش 1: استفاده از یک پرس و جو دقیق با نام مکان و آدرس

https://www.google.com/maps/search/?api=1&query=7-Eleven%2C37%20Swanston%20St%2C%20Melbourne%20Australia

در این URL، پارامتر query به صورت نام مکان، آدرس قالب بندی می شود. این به محدود کردن جستجو و پیوند مستقیم به مکان مورد نظر کمک می کند.

روش 2: استفاده از شناسه مکان

شناسه‌های مکان به طور منحصربه‌فردی یک مکان را در پایگاه داده Google Places و در Google Maps شناسایی می‌کنند.

https://www.google.com/maps/search/?api=1&query=7-Elevan&query_place_id=ChIJGcmcg7ZC1moRAOacd3HoEwM

در اینجا، ChIJGcmcg7ZC1moRAOacd3HoEwM شناسه مکان منحصر به فرد برای مکان خاص است. پارامتر query همچنان مورد نیاز است، اما تنها در صورتی استفاده می شود که Google Maps نتواند شناسه مکان را پیدا کند.

سناریو 4: نمایش جزئیات مکان با استفاده از مختصات طول و عرض جغرافیایی و همچنین شناسه مکان

با استفاده از شناسه مکان، Google Maps اطلاعات دقیق مکان را نشان می دهد.

https://www.google.com/maps/search/?api=1&query=-33.8567%2C151.2152&query_place_id=ChIJ3S-JXmauEmsRUcIaWtf4MzE

صفحه جزئیات مکان با استفاده از طول و عرض جغرافیایی و همچنین شناسه مکان

بازیابی شناسه مکان با هزینه صفر

برای بازیابی برنامه‌نویسی شناسه‌های مکان، می‌توانید از عملکرد Places API: جستجوی متن (فقط شناسه) استفاده کنید. این یک روش هزینه صفر برای دریافت شناسه مکان است. درباره Place ID و Place API (جدید) درخواست بیشتر بیاموزید.

درخواست جستجوی متنی Places API (فقط شناسه):

curl -X POST -d '{"textQuery" : "Sydney Opera House"}'
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY'
-H 'X-Goog-FieldMask: places.id'
'https://places.googleapis.com/v1/places:searchText'

پاسخ جستجوی متن API Places (فقط شناسه):

{
  "places": [
    {
      "id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
    }
  ]
}

شناسه‌های مکان همچنین می‌توانند زمانی که کاربر روی یک POI روی نقشه کلیک یا ضربه می‌زند، بازیابی شود. جزئیات بیشتر در مورد نمادهای POI قابل کلیک ( جاوا اسکریپت ، اندروید ، iOS ) بیابید

نتیجه گیری

ارائه جزئیات دقیق مکان برای یک تجربه مثبت حیاتی است. برای اطمینان از اینکه کاربران در صفحه جزئیات مکان صحیح قرار می گیرند، URL های جستجو را با استفاده از یکی از قالب های توصیه شده زیر بسازید:

• query=PLACE_NAME, ADDRESS
• query=PLACE_NAME&query_place_id=PLACE_ID

زمانی که هدف شما نمایش جزئیات یک مکان خاص است، فقط از مختصات طول و عرض جغرافیایی در پارامتر query استفاده نکنید. قالب‌هایی مانند query=latitude,longitude ، query=PLACE_NAME,latitude,longitude ، یا query=ADDRESS,latitude,longitude به طور مداوم به صفحه جزئیات مکان مورد نظر منتهی نمی‌شوند. در عوض، طول و عرض جغرافیایی مکان را نشان می دهد.

جستجوی دسته بندی با استفاده از URL های Maps

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

سناریو 1: جستجوی مکان های نزدیک

https://www.google.com/maps/search/?api=1&query=Cafe%20near%20Sydney%20Opera%20House%20that%20are%20open%20now

جستجوی طبقه بندی - مکان های نزدیک

ارائه دستورالعمل ها با استفاده از URL های Maps

تابع Directions مسیر بین دو یا چند نقطه مشخص شده روی نقشه و همچنین مسافت و زمان سفر را نمایش می دهد. این به توسعه دهندگان کنترل بیشتری بر مسیرهای ارائه شده ارائه می دهد. GMP's Maps URLs Directions دستورالعمل های دقیقی را در مورد ساخت URL برای مسیرهای سفارشی ارائه می دهد.

ساختار URL Directions:

https://www.google.com/maps/dir/?api=1&parameters

سناریوی 1: یافتن بهترین مسیر از مکان فعلی کاربر به مقصد

https://www.google.com/maps/dir/?api=1&destination=Flinders%20Station%20Melbourne&travelmode=driving

این URL نقشه های گوگل را باز می کند و مسیرهای رانندگی را از مکان فعلی کاربر نمایش می دهد.

در این URL، origin حذف شده است. هنگامی که origin حذف می شود، مسیر به طور پیش فرض به مناسب ترین مکان شروع، مانند مکان دستگاه، در صورت وجود، تنظیم می شود. اگر هیچ کدام، نقشه حاصل فرمی را ارائه می دهد که به کاربر اجازه می دهد مبدا را وارد کند. مقدار مبدا و مقصد می تواند نام مکان، آدرس یا مختصات طول و عرض جغرافیایی جدا شده با کاما باشد.

travelmode یک پارامتر اختیاری است. روش سفر را مشخص می کند. این پارامتر را می توان به صورت زیر تنظیم کرد:

• رانندگی
• راه رفتن
• دوچرخه سواری
• دو چرخ
• ترانزیت

اگر هیچ حالت سفری مشخص نشده باشد، نقشه Google یک یا چند مورد از مرتبط ترین حالت ها را برای مسیر مشخص شده و/یا تنظیمات برگزیده کاربر نشان می دهد.

توسعه دهندگان همچنین می توانند شناسه مکان را با استفاده از پارامتر origin_place_id و destination_place_id تعیین کنند. استفاده از شناسه مکان بهترین تضمین برای پیوند دادن به مکان مناسب است.

بازیابی شناسه مکان با هزینه صفر

برای بازیابی برنامه‌نویسی شناسه‌های مکان، می‌توانید از عملکرد Places API: جستجوی متن (فقط شناسه) استفاده کنید. این یک روش هزینه صفر برای دریافت شناسه مکان است. درباره Place ID و Place API (جدید) درخواست بیشتر بیاموزید.

درخواست جستجوی متنی Places API (فقط شناسه):

curl -X POST -d '{"textQuery" : "Sydney Opera House"}'
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY'
-H 'X-Goog-FieldMask: places.id'
'https://places.googleapis.com/v1/places:searchText'

پاسخ جستجوی متن API Places (فقط شناسه):

{
  "places": [
    {
      "id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
    }
  ]
}

شناسه‌های مکان همچنین می‌توانند زمانی که کاربر روی یک POI روی نقشه کلیک یا ضربه می‌زند، بازیابی شود. جزئیات بیشتر در مورد نمادهای POI قابل کلیک ( جاوا اسکریپت ، اندروید ، iOS ) بیابید

مسیرها از مکان فعلی کاربر

سناریوی 3: ارائه ناوبری گام به گام

https://www.google.com/maps/dir/?api=1&destination=Flinders%20Station%20Melbourne&travelmode=driving&dir_action=navigate

تنظیم dir_action=navigate در URL، اگر موقعیت مکانی فعلی کاربر (موقعیت دستگاه) در دسترس باشد و به عنوان مبدأ در دسترس باشد، Google Maps را در حالت پیمایش گام به گام راه اندازی می کند (چه به طور صریح ارائه شده باشد یا به طور ضمنی در صورت حذف پارامتر مبدا). در غیر این صورت پیش نمایش مسیر نمایش داده می شود.

زمانی که dir_action=navigate تنظیم شده باشد، پیمایش گام به گام راه اندازی می شود و:

• مبدا مشخص شده است و به مکان فعلی کاربر نزدیک است
• مبدا حذف شده است و مکان فعلی کاربر در دسترس است

پیش نمایش مسیر زمانی راه اندازی می شود که:

• dir_action=navigate تنظیم نشده است
• dir_action=navigate تنظیم شده و مبدا مشخص شده است و مبدا به مکان فعلی کاربر نزدیک نیست
• dir_action=navigate تنظیم شده است و مبدا حذف شده است و مکان فعلی کاربر در دسترس نیست

توجه داشته باشید که پیمایش در همه محصولات Google Maps مانند Google Maps Web و/یا بین همه مقصدها در دسترس نیست. در این موارد این پارامتر نادیده گرفته می شود.

ناوبری گام به گام	پیش نمایش مسیر

نتیجه گیری

با ساخت صحیح URL های Maps، می توانید اطمینان حاصل کنید که کاربران اطلاعات مناسب مورد نیاز خود را به سرعت و کارآمد دریافت می کنند.

• همیشه مقصد را مشخص کنید و برای دقت تضمین شده در صورت امکان از شناسه مکان استفاده کنید

• هنگامی که هدف ارائه ناوبری فوری است، پارامتر dir_action=navigate را برای راه اندازی ناوبری گام به گام اضافه کنید. در صورتی که مکان دستگاه در دسترس باشد و از آن به عنوان مبدأ استفاده شود (به طور صریح تنظیم شده باشد یا حذف شده باشد) پیمایش از مکان فعلی کاربر شروع می شود.

انتخاب رویکرد مناسب برای برنامه شما

شما دو گزینه اصلی دارید: استفاده از URL های از پیش قالب بندی شده ارائه شده توسط Places API یا ساخت دستی URL های Maps در برنامه شما. هر رویکرد مجموعه ای از مزایا و معایب خاص خود را دارد.

Places API:

• فیلدهای googleMapsUri و googleMapsLinks در پاسخ Place Details URL های آماده برای استفاده را ارائه می دهند. این امر زمان توسعه را کاهش می دهد و خطر خطا در قالب بندی URL را به حداقل می رساند.

• کنترل کمتری بر پیکربندی جهت ها فراهم می کند. در حالی که googleMapsLinks دستورالعمل های اساسی را ارائه می دهد، از ایستگاه های بین راه یا سفارشی سازی پیشرفته پشتیبانی نمی کند. همچنین، راه اندازی مستقیم ناوبری گام به گام نسبتاً ساده نیست.

آدرس های اینترنتی نقشه ها:

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

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

بهبود URL های Maps با پارامترهای UTM

برای کمک به Google برای درک بهتر نحوه ادغام نشانی‌های وب Maps توسط توسعه‌دهندگان و اطمینان از عملکرد بهینه، شما را تشویق می‌کنیم که پارامترهای ردیابی UTM را در ساخت URL خود بگنجانید. با افزودن پارامترهای utm_source و utm_campaign ، داده‌های ارزشمندی را ارائه می‌دهید که به ما امکان می‌دهد الگوهای استفاده را تجزیه و تحلیل کنیم و محصول Maps URLs را بهبود ببخشیم.

برای پارامتر utm_source ، از نام برنامه خود استفاده کنید. پارامتر utm_campaign باید عملکرد مورد نظر کاربر را منعکس کند، مانند "location_sharing"، "place_details_search" یا "directions_request".

برای مثال، یک URL با پارامترهای UTM ممکن است به شکل زیر باشد:

https://www.google.com/maps/search/?api=1&query=Sydney+Opera+House&query_place_id=ChIJ3S-JXmauEmsRUcIaWtf4MzE&utm_source=YourAppName&utm_campaign=place_details_search

استفاده مداوم از این پارامترها به ما کمک می کند تا زمینه های بهبود را شناسایی کنیم، مشکلات را به طور موثرتر عیب یابی کنیم و در نهایت تجربه بهتری را برای همه کاربران ارائه کنیم.

مراحل بعدی

پیشنهاد مطالعه بیشتر:

• URL نقشه ها
• شناسه های مکان
• Places API - پیوند به Google Maps
• Routes API

مشارکت کنندگان

نویسندگان اصلی:

ترزا کین | مهندس راه حل های پلتفرم نقشه های گوگل