Geocoding API v4 دو خانواده قابلیت اصلی ارائه می‌دهد: جستجوی مقصد برای مشخصه‌های غنی محلی، و زمین‌کدیابی پایه (تبدیل مختصات به نشانی). مطمئن نیستید از کدام روش استفاده کنید؟ انتخاب روش زمین‌کدیابی را ببینید.
- جستجوی مقصدها (
SearchDestinations): جزئیات غنی ورود به مقصد را بازیابی می‌کند—ازجمله ورودی‌های ساختمان، نقاط ناوبری قابل‌یابی، طرح کلی ساختمان/زمین، زیرمقصدها، و نشان‌های نزدیک. - زمین‌کدیابی (
GeocodeAddress): نشانی‌های خیابان را به مختصات طول و عرض جغرافیایی تبدیل می‌کند تا نشانگرهای اصلی را قرار دهد یا نقشه را در مرکز قرار دهد. - زمین‌کدیابی معکوس (
GeocodeLocation): مختصات جغرافیایی را به نشانی خیابان قابل‌خواندن برای انسان تبدیل می‌کند. - زمین‌کدیابی مکان (
GeocodePlace): نشانی قالب‌بندی‌شده و مختصات را برای شناسه مکان شناخته‌شده پیدا می‌کند.
نمونه درخواست‌ها و پاسخ‌ها
ازطریق میانای HTTP به Geocoding API دسترسی پیدا می‌کنید. در زیر نمونه‌های شروع سریع برای جستجوی مقصد، زمین‌کدیابی مستقیم، و زمین‌کدیابی معکوس آورده شده است.
درخواست و پاسخ جستجوی مقصدها (داده‌های ورود محلی)
مثال زیر درخواست HTTP POST را برای «1600 Amphitheatre Parkway, Mountain View, CA» به SearchDestinations ارسال می‌کند. توجه داشته باشید که SearchDestinations به سرصفحه X-Goog-FieldMask نیاز دارد که فیلدهای برگشتی را مشخص می‌کند:
curl -X POST -d '{ "addressQuery": { "addressQuery": "1600 Amphitheatre Parkway, Mountain View, CA" } }' \ -H 'Content-Type: application/json' \ -H 'X-Goog-FieldMask: destinations.primary.displayName,destinations.primary.formattedAddress,destinations.primary.location,destinations.primary.displayPolygon,destinations.entrances,destinations.navigationPoints,destinations.landmarks' \ -H "X-Goog-Api-Key: YOUR_API_KEY" \ "https://geocode.googleapis.com/v4/geocode/destinations"
در زیر نمونه‌ای از پاسخ SearchDestinations نشان داده شده است که چندضلعی سطح اشغال ساختمان، ورودی‌های ترجیحی، نقاط ناوبری قابل‌یابی، و نشان‌های مکانی اطراف را نشان می‌دهد:
{ "destinations": [ { "primary": { "displayName": { "text": "Googleplex", "languageCode": "en" }, "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "location": { "latitude": 37.4220656, "longitude": -122.0840897 }, "displayPolygon": { "type": "Polygon", "coordinates": [ [ [-122.084958, 37.422145], [-122.084112, 37.422610], [-122.083510, 37.421980], [-122.084958, 37.422145] ] ] } }, "entrances": [ { "location": { "latitude": 37.422189, "longitude": -122.084215 }, "tags": ["PREFERRED"] } ], "navigationPoints": [ { "navigationPointToken": "Eg...", "displayName": { "text": "Amphitheatre Pkwy Dropoff", "languageCode": "en" }, "location": { "latitude": 37.421912, "longitude": -122.084301 }, "travelModes": ["DRIVE"], "usages": ["DROPOFF", "PICKUP"] } ], "landmarks": [ { "place": { "displayName": { "text": "Charleston Park", "languageCode": "en" } }, "relationalDescription": { "text": "Adjacent to Charleston Park", "languageCode": "en" }, "straightLineDistanceMeters": 85.4 } ] } ] }
درخواست و پاسخ زمین‌کدیابی (جستجوی طول/عرض جغرافیایی)
مثال زیر طول و عرض جغرافیایی «1600 Amphitheatre Parkway, Mountain View, CA» را درخواست می‌کند و مشخص می‌کند که خروجی باید در قالب JSON باشد.
curl -H "X-Goog-Api-Key: YOUR_API_KEY" \ "https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"
می‌توانید این را با وارد کردن نشانی وب در مرورگر وب خود آزمایش کنید (حتماً
YOUR_API_KEY را با کلید میانای برنامه‌سازی کاربردی واقعی خود جایگزین کنید).
پاسخ شامل طول و عرض جغرافیایی نشانی است.
راهنمای توسعه‌دهنده را برای اطلاعات بیشتر درباره ساختن نشانی‌های وب درخواست زمین‌کدیابی، پارامترهای دردسترس و درک پاسخ مشاهده کنید.
در زیر نمونه‌ای از پاسخ زمین‌کدیابی در قالب JSON آمده است:
{ "results": [ { "place": "//places.googleapis.com/places/ChIJ2Z2idB66j4ARI43TG-9RoCQ", "placeId": "ChIJ2Z2idB66j4ARI43TG-9RoCQ", "location": { "latitude": 37.4438238, "longitude": -122.0869895 }, "granularity": "ROOFTOP", "viewport": { "low": { "latitude": 37.4424748197085, "longitude": -122.0883384802915 }, "high": { "latitude": 37.445172780291493, "longitude": -122.08564051970852 } }, "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94043-1351", "administrativeArea": "CA", "locality": "Mountain View", "addressLines": [ "1600 Amphitheatre Pkwy" ] }, "addressComponents": [ { "longText": "1600", "shortText": "1600", "types": [ "street_number" ] }, { "longText": "Amphitheatre Parkway", "shortText": "Amphitheatre Pkwy", "types": [ "route" ], "languageCode": "en" }, { "longText": "Mountain View", "shortText": "Mountain View", "types": [ "locality", "political" ], "languageCode": "en" }, { "longText": "Santa Clara County", "shortText": "Santa Clara County", "types": [ "administrative_area_level_2", "political" ], "languageCode": "en" }, { "longText": "California", "shortText": "CA", "types": [ "administrative_area_level_1", "political" ], "languageCode": "en" }, { "longText": "United States", "shortText": "US", "types": [ "country", "political" ], "languageCode": "en" }, { "longText": "94043", "shortText": "94043", "types": [ "postal_code" ] }, { "longText": "1351", "shortText": "1351", "types": [ "postal_code_suffix" ] } ], "types": [ "premise", "street_address" ] } ] }
درخواست و پاسخ زمین‌کدیابی معکوس (جستجوی نشانی)
مثال زیر نشانی مربوط به طول/عرض جغرافیایی داده‌شده در بروکلین، نیویورک، ایالات متحده را درخواست می‌کند. مشخص می‌کند که خروجی باید در قالب JSON باشد.
https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?key=YOUR_API_KEYمی‌توانید این را با وارد کردن نشانی وب در مرورگر وب خود آزمایش کنید (حتماً «YOUR_API_KEY» را با کلید میانای برنامه‌سازی کاربردی واقعی خود جایگزین کنید). پاسخ شامل نشانی قابل‌خواندن برای انسان برای مکان طول و عرض جغرافیایی است.
برای اطلاعات بیشتر درباره ساختن نشانی‌های وب درخواست زمین‌کدیابی معکوس، پارامترهای دردسترس، و درک پاسخ، راهنمای توسعه‌دهنده را ببینید.
در زیر نمونه‌ای از پاسخ زمین‌کدیابی معکوس در قالب JSON آورده شده است:
{ "results": [ { "place": "//places.googleapis.com/places/ChIJHRNUiQK6j4ARJ__Hrbt6qsE", "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE", "location": { "latitude": 37.4225657, "longitude": -122.08465439999999 }, "granularity": "ROOFTOP", "viewport": { "low": { "latitude": 37.421214719708509, "longitude": -122.08603273029148 }, "high": { "latitude": 37.423912680291508, "longitude": -122.0833347697085 } }, "bounds": { "low": { "latitude": 37.4225178, "longitude": -122.08484599999998 }, "high": { "latitude": 37.422609600000008, "longitude": -122.0845215 } }, "formattedAddress": "Google Building 40, 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94043", "administrativeArea": "CA", "locality": "Mountain View", "addressLines": [ "Google Building 40", "1600 Amphitheatre Pkwy" ] }, "addressComponents": [ { "longText": "Google Building 40", "shortText": "Google Building 40", "types": [ "premise" ], "languageCode": "en" }, { "longText": "1600", "shortText": "1600", "types": [ "street_number" ] }, { "longText": "Amphitheatre Parkway", "shortText": "Amphitheatre Pkwy", "types": [ "route" ], "languageCode": "en" }, { "longText": "Mountain View", "shortText": "Mountain View", "types": [ "locality", "political" ], "languageCode": "en" }, { "longText": "Santa Clara County", "shortText": "Santa Clara County", "types": [ "administrative_area_level_2", "political" ], "languageCode": "en" }, { "longText": "California", "shortText": "CA", "types": [ "administrative_area_level_1", "political" ], "languageCode": "en" }, { "longText": "United States", "shortText": "US", "types": [ "country", "political" ], "languageCode": "en" }, { "longText": "94043", "shortText": "94043", "types": [ "postal_code" ] } ], "types": [ "street_address", "subpremise" ] }, ... Additional results truncated in this example[] ... }
اصالت‌سنجی، سهمیه‌ها، قیمت‌گذاری، و خط‌مشی‌ها
اصالت‌سنجی
برای استفاده از Geocoding API، ابتدا باید API را فعال کنید و اعتبارنامه‌های اصالت‌سنجی مناسب را دریافت کنید. برای اطلاعات بیشتر، به شروع به کار با Google Maps Platform مراجعه کنید.
سهمیه‌ها و قیمت‌گذاری
برای اطلاع از جزئیات مربوط به سهمیه‌ها و قیمت‌گذاری تعیین‌شده برای Geocoding API، صفحه استفاده و صدور صورت‌حساب را مرور کنید.
خط‌مشی‌ها
استفاده از Geocoding API باید مطابق با خط‌مشی‌های API باشد.