راهنمای امنیتی پلتفرم نقشه های گوگل

برنامه‌ها و پروژه‌هایی که از APIها و SDKهای پلتفرم نقشه‌های گوگل استفاده می‌کنند، باید از کلیدهای API یا در صورت پشتیبانی، از OAuth 2.0 برای احراز هویت خود استفاده کنند.

این بهترین شیوه‌ها به شما نشان می‌دهند که چگونه دسترسی به پلتفرم نقشه‌های خود را ایمن کنید.

اگر می‌خواهید از OAuth 2.0 برای تأیید ترافیک سرور به سرور استفاده کنید، موضوع OAuth را در مستندات API خود جستجو کنید. برای جزئیات بیشتر به بخش «استفاده از OAuth برای برنامه‌های سمت سرور» مراجعه کنید.

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

اگر کلیدهای API شما از قبل در حال استفاده هستند، توصیه‌های زیر را در بخش «اگر می‌خواهید یک کلید API در حال استفاده را محدود کنید» مرور کنید.

برای جزئیات بیشتر در مورد امضاهای دیجیتال، که توسط Maps Static API و Street View Static API پشتیبانی می‌شوند، به راهنمای امضای دیجیتال مراجعه کنید.

بهترین شیوه‌های توصیه‌شده

برای افزایش امنیت و جلوگیری از پرداخت هزینه برای استفاده غیرمجاز، این شیوه‌های برتر امنیتی API را برای همه APIها، SDKها یا سرویس‌های پلتفرم نقشه‌های گوگل دنبال کنید:

برای همه کاربردهای کلید API توصیه می‌شود

کلیدهای API خود را محدود کنید

برای هر برنامه از کلیدهای API جداگانه استفاده کنید

کلیدهای API استفاده نشده را حذف کنید

میزان استفاده از کلید API خود را بررسی کنید

هنگام چرخاندن کلیدهای API مراقب باشید

تقسیم استفاده از سمت کلاینت و سمت سرور به پروژه‌های جداگانه

غیرفعال کردن سرویس‌های بلااستفاده

توصیه‌های اضافی برای برنامه‌های سمت کلاینت

استفاده از SDK های سمت کلاینت

ایمن‌سازی فراخوانی‌های سرویس وب سمت کلاینت

توصیه‌های بیشتر برای وب‌سایت‌ها یا برنامه‌های سمت کلاینت که از APIهای وب استاتیک استفاده می‌کنند

محافظت از استفاده از API وب استاتیک

توصیه‌های اضافی برای برنامه‌های سمت سرور با استفاده از سرویس‌های وب

محافظت از کلیدهای API سرویس وب

استفاده از OAuth برای برنامه‌های سمت سرور

اگر در حال محدود کردن یا تغییر کلید API در حال استفاده هستید

• قبل از تغییر کلید API، میزان استفاده از کلید API خود را بررسی کنید. این مرحله به ویژه در صورتی اهمیت دارد که بخواهید محدودیت‌هایی را برای کلیدی که از قبل در یک برنامه کاربردی در حال استفاده است، اضافه کنید.

• پس از تغییر کلید، در صورت نیاز، تمام برنامه‌های خود را با کلیدهای API جدید به‌روزرسانی کنید.

• اگر کلید API شما لو نرفته و مورد سوءاستفاده‌ی فعال قرار نگرفته باشد، می‌توانید برنامه‌های خود را با سرعت دلخواه خود به چندین کلید API جدید منتقل کنید و کلید API اصلی را تا زمانی که فقط یک نوع ترافیک مشاهده نکنید، دست‌نخورده باقی بگذارید و کلید API را می‌توان با خیال راحت با یک نوع محدودیت برنامه محدود کرد، بدون اینکه باعث ایجاد اختلالات ناخواسته در سرویس شود.

  برای دستورالعمل‌های بیشتر، به Migrate to multiple API keys مراجعه کنید.

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

• اگر کلید API شما لو رفته است، می‌خواهید سریع‌تر برای ایمن‌سازی کلید API خود و جلوگیری از سوءاستفاده اقدام کنید. در برنامه‌های اندروید و iOS، کلیدها تا زمانی که مشتریان برنامه‌های خود را به‌روزرسانی نکنند، جایگزین نمی‌شوند. به‌روزرسانی یا جایگزینی کلیدها در صفحات وب یا برنامه‌های سمت سرور بسیار ساده‌تر است، اما هنوز هم ممکن است نیاز به برنامه‌ریزی دقیق و کار سریع داشته باشد.

  برای اطلاعات بیشتر، به بخش «مدیریت استفاده غیرمجاز از کلید API» مراجعه کنید.

اطلاعات بیشتر

محدودیت‌های پیشنهادی برای برنامه‌ها و API

کلیدهای API خود را محدود کنید

بهترین روش این است که همیشه کلیدهای API خود را با یک نوع محدودیت برنامه و یک یا چند محدودیت API محدود کنید. برای محدودیت‌های پیشنهادی بر اساس API، SDK یا سرویس جاوا اسکریپت، به محدودیت‌های پیشنهادی برنامه و API در زیر مراجعه کنید.

• محدودیت‌های برنامه شما می‌توانید استفاده از کلید API را به پلتفرم‌های خاصی محدود کنید: برنامه‌های اندروید یا iOS، یا وب‌سایت‌های خاص برای برنامه‌های سمت کلاینت، یا آدرس‌های IP خاص یا زیرشبکه‌های CIDR برای برنامه‌های سمت سرور که فراخوانی‌های REST API سرویس وب را صادر می‌کنند.

  شما با اضافه کردن یک یا چند محدودیت کاربردی از انواعی که می‌خواهید مجاز کنید، یک کلید را محدود می‌کنید، و پس از آن فقط درخواست‌های ارسالی از این منابع مجاز می‌شوند.

• محدودیت‌های API شما می‌توانید APIها، SDKها یا سرویس‌های پلتفرم نقشه‌های گوگل را که کلید API شما می‌تواند در آنها استفاده شود، محدود کنید. محدودیت‌های API فقط درخواست‌ها را به APIها و SDKهایی که شما مشخص می‌کنید، مجاز می‌دانند. برای هر کلید API مشخص، می‌توانید هر تعداد محدودیت API که لازم باشد، تعیین کنید. لیست APIهای موجود شامل تمام APIهای فعال در یک پروژه است.

تنظیم محدودیت برنامه برای کلید API

1. صفحه اعتبارنامه‌های پلتفرم نقشه‌های گوگل (Google Maps Platform Credentials) در کنسول گوگل کلود (Google Cloud console) را باز کنید.

2. کلید API مورد نظر برای محدود کردن را انتخاب کنید.

3. در صفحه ویرایش کلید API ، در قسمت محدودیت‌های کلید ، گزینه تنظیم محدودیت برنامه را انتخاب کنید.

   

4. یکی از انواع محدودیت‌ها را انتخاب کنید و اطلاعات درخواستی را مطابق فهرست محدودیت‌ها ارائه دهید.

   نوع محدودیت	توضیحات
   وب‌سایت‌ها	یک یا چند وب‌سایت ارجاع‌دهنده را مشخص کنید. طرح‌های URI ارجاع‌دهنده که به طور جهانی پشتیبانی می‌شوند، https و http هستند. تضمینی برای عملکرد صحیح طرح‌های دیگر وجود ندارد، زیرا مرورگرهای وب مدرن به دلایل حفظ حریم خصوصی، هدر «ارجاع‌دهنده» را در درخواست‌های خروجی ارسال نمی‌کنند. همیشه کل رشته ارجاع، شامل طرح پروتکل، نام میزبان و پورت اختیاری (مثلاً https://google.com ) را ارائه دهید. شما می‌توانید از کاراکترهای wildcard برای تأیید همه زیر دامنه‌ها استفاده کنید. برای مثال، https://*.google.com همه سایت‌هایی را که به .google.com ختم می‌شوند، می‌پذیرد. هنگام تأیید ارجاع‌دهنده‌های مسیر کامل، مثلاً https://google.com/some/path ، مراقب باشید، زیرا اکثر مرورگرهای وب به دلایل حفظ حریم خصوصی، مسیر را از درخواست‌های بین‌مرجعی حذف می‌کنند.
   آدرس‌های IP	یک یا چند آدرس IPv4 یا IPv6 یا زیرشبکه‌ها را با استفاده از نمادگذاری CIDR مشخص کنید. آدرس‌های IP باید با آدرس منبعی که سرورهای پلتفرم نقشه‌های گوگل مشاهده می‌کنند، مطابقت داشته باشند. اگر از ترجمه آدرس شبکه (NAT) استفاده می‌کنید، این آدرس معمولاً با آدرس IP عمومی دستگاه شما مطابقت دارد.
   برنامه‌های اندروید	نام بسته اندروید (از فایل AndroidManifest.xml ) و اثر انگشت گواهی امضای SHA-1 هر برنامه اندرویدی که می‌خواهید مجاز کنید را اضافه کنید. برنامه‌های اندروید را انتخاب کنید. روی + افزودن کلیک کنید. نام بسته و اثر انگشت گواهی SHA-1 خود را وارد کنید. برای مثال: com.example.android.mapexample BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75 روی ذخیره کلیک کنید. دو نوع گواهی وجود دارد: گواهی اشکال‌زدایی : فقط از این نوع گواهی برای برنامه‌هایی که آزمایش می‌کنید و سایر کدهای غیرتولیدی استفاده کنید. سعی نکنید برنامه‌ای را که با گواهی اشکال‌زدایی امضا شده است منتشر کنید. ابزارهای SDK اندروید هنگام اجرای یک نسخه اشکال‌زدایی، این گواهی را به‌طور خودکار تولید می‌کنند. گواهی انتشار : از این گواهی زمانی استفاده کنید که آماده انتشار برنامه خود در یک فروشگاه برنامه هستید. ابزارهای SDK اندروید این گواهی را هنگام اجرای نسخه آزمایشی تولید می‌کنند. برای اطلاعات بیشتر در مورد امضای برنامه اندروید و گواهینامه‌ها، به راهنمای امضای برنامه خود مراجعه کنید. اگر از امضای برنامه Play برای دریافت اثر انگشت گواهی امضا استفاده می‌کنید، به بخش «کار با ارائه‌دهندگان API» مراجعه کنید. اگر کلید امضای خود را مدیریت می‌کنید، به «امضای خودکار برنامه» مراجعه کنید یا به دستورالعمل‌های محیط ساخت خود مراجعه کنید.
   اپلیکیشن‌های iOS	شناسه بسته نرم‌افزاری هر برنامه iOS که می‌خواهید مجاز کنید را اضافه کنید. برنامه‌های iOS را انتخاب کنید. روی + افزودن کلیک کنید. شناسه بسته (bundle ID) را برای پذیرش درخواست‌ها از برنامه iOS با آن شناسه اضافه کنید. روی ذخیره کلیک کنید.

   برای توصیه‌هایی برای محدودیت برنامه، به محدودیت برنامه پیشنهادی مراجعه کنید.

5. ذخیره را انتخاب کنید.

تنظیم محدودیت‌های API برای یک کلید API

1. صفحه اعتبارنامه‌های پلتفرم نقشه‌های گوگل (Google Maps Platform Credentials) در کنسول گوگل کلود (Google Cloud console) را باز کنید.

2. کلید API مورد نظر برای محدود کردن را انتخاب کنید.

3. در صفحه ویرایش کلید API ، در قسمت محدودیت‌های API :

   • کلید محدود کردن را انتخاب کنید.

   • بخش Select APIs را باز کنید و APIها یا SDKهایی را که می‌خواهید برنامه‌تان با استفاده از کلید API به آنها دسترسی داشته باشد، انتخاب کنید.

   اگر API یا SDK مورد نظر در لیست نیست، باید آن را فعال کنید. برای جزئیات بیشتر، به بخش فعال کردن یک یا چند API یا SDK مراجعه کنید.

   

4. ذخیره را انتخاب کنید.

   این محدودیت پس از این مرحله بخشی از تعریف کلید API می‌شود. مطمئن شوید که جزئیات مناسب را ارائه می‌دهید و برای ذخیره محدودیت‌های کلید API خود، گزینه «ذخیره» را انتخاب کنید. برای اطلاعات بیشتر، به راهنمای «دریافت کلید API» در مستندات مربوط به API یا SDK خاص مورد نظر خود مراجعه کنید.

برای محدودیت‌های توصیه‌شده API، به محدودیت‌های توصیه‌شده API مراجعه کنید.

میزان استفاده از کلید API خود را بررسی کنید

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

• APIهایی که از کلید API شما استفاده می‌کنند را تعیین کنید

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

APIهایی که از کلید API شما استفاده می‌کنند را تعیین کنید

گزارش‌های معیارهای زیر به شما امکان می‌دهند تعیین کنید کدام APIها از کلیدهای API شما استفاده می‌کنند. از این گزارش‌ها برای انجام موارد زیر استفاده کنید:

• ببینید چگونه از کلیدهای API شما استفاده می‌شود
• استفاده غیرمنتظره را تشخیص دهید
• به بررسی ایمن بودن حذف یک کلید استفاده نشده کمک کنید. برای اطلاعات بیشتر در مورد حذف یک کلید API، به «حذف کلیدهای API استفاده نشده» مراجعه کنید.

هنگام اعمال محدودیت‌های API، از این گزارش‌ها برای ایجاد فهرستی از APIها برای تأیید یا اعتبارسنجی توصیه‌های محدودیت کلید API که به صورت خودکار ایجاد شده‌اند، استفاده کنید. برای اطلاعات بیشتر در مورد محدودیت‌های توصیه‌شده، به اعمال محدودیت‌های توصیه‌شده مراجعه کنید. برای اطلاعات بیشتر در مورد استفاده از کاوشگر Metrics، به ایجاد نمودار با کاوشگر Metrics مراجعه کنید.

1. به جستجوگر معیارهای کنسول گوگل کلود بروید

2. وارد سیستم شوید و پروژه مربوط به کلیدهای API مورد نظر خود را انتخاب کنید.

3. برای نوع API خود به صفحه کاوشگر معیارها بروید:

   • برای کلیدهای API که از هر API به جز Maps Embed API استفاده می‌کنند : به صفحه کاوشگر معیارها بروید.

   • برای کلیدهای API با استفاده از Maps Embed API : به Metrics Explorer بروید.

4. هر کلید API را بررسی کنید:

   1. گزینه افزودن فیلتر را انتخاب کنید.

   2. برچسب credential_id را انتخاب کنید.

   3. مقدار مربوط به کلیدی که می‌خواهید بررسی کنید را انتخاب کنید.

   4. توجه داشته باشید که این کلید API برای کدام APIها استفاده می‌شود و تأیید کنید که این استفاده مورد انتظار است.

   5. پس از انجام این کار، در انتهای خط فیلتر فعال، گزینه Remove filter delete را انتخاب کنید تا فیلتر اضافی حذف شود.

5. برای کلیدهای باقی مانده تکرار کنید.

6. کلیدهای API خود را فقط به APIهایی که استفاده می‌شوند محدود کنید.

7. اگر متوجه استفاده غیرمجاز شدید، به بخش «مدیریت استفاده غیرمجاز از کلید API» مراجعه کنید.

با استفاده از کاوشگر معیارها، نوع صحیح محدودیت برنامه را انتخاب کنید

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

اگر کلید API شما محدودیت‌های کلید API توصیه‌شده‌ای دارد، آن‌ها را اعمال کنید. برای اطلاعات بیشتر، به «اعمال محدودیت‌های کلید API توصیه‌شده» مراجعه کنید.

اگر کلید API شما توصیه‌های محدودیتی ندارد، نوع محدودیت برنامه‌ای که می‌خواهید اعمال کنید را بر اساس platform_type گزارش‌شده با استفاده از کاوشگر Metrics تعیین کنید:

1. به جستجوگر معیارهای کنسول گوگل کلود بروید

2. وارد سیستم شوید و پروژه مربوط به APIهایی که می‌خواهید بررسی کنید را انتخاب کنید.

3. به این صفحه‌ی جستجوگر معیارها بروید: جستجوگر معیارها .

4. هر کلید API را بررسی کنید:

   1. گزینه افزودن فیلتر را انتخاب کنید.

   2. برچسب credential_id را انتخاب کنید.

   3. مقدار مربوط به کلیدی که می‌خواهید بررسی کنید را انتخاب کنید.

   4. پس از انجام این کار، در انتهای خط فیلتر فعال، گزینه Remove filter delete را انتخاب کنید تا فیلتر اضافی حذف شود.

5. برای کلیدهای باقی مانده تکرار کنید.

6. وقتی نوع پلتفرم را برای کلیدهای API خود مشخص کردید، محدودیت برنامه را برای آن platform_type اعمال کنید:

   PLATFORM_TYPE_JS : محدودیت‌های وب‌سایت را روی کلید اعمال می‌کند.

   PLATFORM_TYPE_ANDROID : محدودیت‌های برنامه‌های اندروید را روی کلید اعمال می‌کند.

   PLATFORM_TYPE_IOS : محدودیت‌های برنامه‌های iOS را روی کلید اعمال می‌کند.

   PLATFORM_TYPE_WEBSERVICE : برای محدود کردن صحیح کلید، ممکن است مجبور شوید به محدودیت‌های آدرس IP روی آن تکیه کنید.

   برای توصیه‌هایی در مورد API استاتیک نقشه‌ها و API استاتیک نمای خیابان، به بخش «حفاظت از کاربرد API استاتیک وب» مراجعه کنید.

   برای توصیه‌های مربوط به API جاسازی نقشه‌ها، به وب‌سایت‌های دارای API جاسازی نقشه‌ها مراجعه کنید.

   کلید API من از چندین نوع پلتفرم استفاده می‌کند: ترافیک شما نمی‌تواند به درستی با یک کلید API واحد ایمن شود. شما باید به چندین کلید API مهاجرت کنید. برای اطلاعات بیشتر، به «مهاجرت به چندین کلید API» مراجعه کنید.

برای هر برنامه از کلیدهای API جداگانه استفاده کنید

این روش، دامنه هر کلید را محدود می‌کند. اگر یک کلید API به خطر بیفتد، می‌توانید کلید آسیب‌دیده را بدون نیاز به به‌روزرسانی سایر کلیدهای API خود حذف یا تغییر دهید. می‌توانید تا ۳۰۰ کلید API در هر پروژه ایجاد کنید. برای اطلاعات بیشتر، به محدودیت‌های کلیدهای API مراجعه کنید.

اگرچه یک کلید API برای هر برنامه برای اهداف امنیتی ایده‌آل است، اما می‌توانید از کلیدهای محدود شده در چندین برنامه استفاده کنید، مادامی که از همان نوع محدودیت برنامه استفاده کنند.

محدودیت‌های توصیه‌شده برای کلید API را اعمال کنید

برای برخی از صاحبان پروژه، ویراستاران و مدیران کلید API، کنسول Google Cloud محدودیت‌های خاصی را برای کلید API بدون محدودیت بر اساس میزان استفاده و فعالیت آنها در پلتفرم Google Maps پیشنهاد می‌دهد.

در صورت وجود، توصیه‌ها به صورت گزینه‌های از پیش پر شده در صفحه اعتبارنامه‌های پلتفرم نقشه‌های گوگل نمایش داده می‌شوند.

APIها و SDKهای پلتفرم نقشه‌های گوگل که توسط توصیه‌های خودکار پشتیبانی می‌شوند

• API جاوا اسکریپت نقشه‌ها، شامل سرویس مسیرها (قدیمی)، سرویس ماتریس فاصله (قدیمی)، سرویس ارتفاع، سرویس ژئوکدینگ کلاس مکان، ویجت تکمیل خودکار مکان (جدید)، API داده‌های تکمیل خودکار مکان، کتابخانه مکان‌ها، سرویس مکان‌ها، ویجت تکمیل خودکار مکان و کیت رابط کاربری مکان‌ها

• API استاتیک نقشه‌ها و API استاتیک نمای خیابان

• API جاسازی نقشه‌ها

• کیت توسعه نرم‌افزار نقشه‌ها برای اندروید، کیت توسعه نرم‌افزار ناوبری برای اندروید، کیت توسعه نرم‌افزار مکان‌ها برای اندروید و کیت رابط کاربری مکان‌ها در اندروید

• کیت توسعه نرم‌افزار نقشه‌ها برای iOS، کیت توسعه نرم‌افزار ناوبری برای iOS، کیت توسعه نرم‌افزار مکان‌ها برای iOS، کیت توسعه نرم‌افزار سوئیفت مکان‌ها برای iOS و کیت رابط کاربری مکان‌ها در iOS.

دلایلی که ممکن است یک توصیه را نبینید یا یک توصیه ناقص را ببینید

دلایل عدم مشاهده توصیه

• شما (همچنین) در حال استفاده از کلید API در سرویس‌هایی غیر از سرویس‌های پلتفرم نقشه‌های گوگل یا سرویس‌های پلتفرم نقشه‌هایی هستید که هنوز توسط توصیه‌های خودکار پشتیبانی نمی‌شوند .

  اگر در سرویس‌های دیگر شاهد استفاده از آن هستید، بدون انجام موارد زیر، این توصیه را اعمال نکنید :

  1. تأیید کنید که استفاده از API که در مرورگر معیارهای کنسول Google Cloud مشاهده می‌کنید، قانونی است.

  2. سرویس‌های ناموجود را به صورت دستی به لیست APIهایی که باید مجاز شوند اضافه کنید .

  3. هرگونه محدودیت برنامه‌ای که برای سرویس‌های اضافه شده به لیست API وجود ندارد را به صورت دستی اضافه کنید . اگر مورد اضافه شده شما به نوع متفاوتی از محدودیت‌های برنامه نیاز دارد، به Migrate to multiple API keys مراجعه کنید.

• کلید API شما در SDKها یا APIهای سمت کلاینت استفاده نمی‌شود.

• شما از کلید API در یک برنامه یا وب‌سایت کم‌حجم استفاده می‌کنید که در ۶۰ روز گذشته هیچ کاربردی نداشته است.

• شما اخیراً یک کلید جدید ایجاد کرده‌اید، یا اخیراً یک کلید موجود را در یک برنامه جدید مستقر کرده‌اید. در این صورت، فقط چند روز دیگر صبر کنید تا توصیه‌ها به‌روزرسانی شوند.

• شما از کلید API در چندین برنامه استفاده می‌کنید که به انواع متناقضی از محدودیت‌های برنامه نیاز دارند، یا از یک کلید API مشابه در برنامه‌ها یا وب‌سایت‌های مختلف زیادی استفاده می‌کنید. در هر دو صورت، به عنوان بهترین روش، باید به چندین کلید مهاجرت کنید. برای جزئیات بیشتر، به «مهاجرت به چندین کلید API» مراجعه کنید.

دلایل مشاهده یک توصیه‌نامه ناقص

• شما از کلید API در یک برنامه یا وب‌سایت کم‌حجم استفاده می‌کنید که در ۶۰ روز گذشته هیچ کاربردی نداشته است.

• شما اخیراً شروع به استفاده از یک کلید موجود در یک API یا سرویس جدید کرده‌اید، و خط لوله توصیه محدودیت کلید API خودکار، هنوز معیارهای استفاده به‌روز شده را پردازش نکرده است. انتشار معیارهای استفاده ممکن است چند روز طول بکشد.

  اگر در سرویس‌های دیگر شاهد استفاده از آن هستید، بدون انجام موارد زیر، این توصیه را اعمال نکنید :

  1. تأیید کنید که استفاده از API که در مرورگر معیارهای کنسول Google Cloud مشاهده می‌کنید، قانونی است.

  2. سرویس‌های ناموجود را به صورت دستی به لیست APIهایی که باید مجاز شوند اضافه کنید .

  3. هرگونه محدودیت برنامه‌ای که برای سرویس‌های اضافه شده به لیست API وجود ندارد را به صورت دستی اضافه کنید . اگر مورد اضافه شده شما به نوع متفاوتی از محدودیت‌های برنامه نیاز دارد، به Migrate to multiple API keys مراجعه کنید.

  4. مگر اینکه فوراً نیاز به محدود کردن یک کلید داشته باشید، مثلاً به دلیل استفاده غیرمجاز، می‌توانید یک یا دو روز صبر کنید تا توصیه‌ها به نتیجه برسند.

دلایلی که ممکن است توصیه‌هایی را ببینید که در نمودارها قابل مشاهده نیستند

• برنامه یا وب‌سایت شما فقط ترافیک بسیار کوتاهی ارسال کرده است. در این حالت، از نمای CHART به نمایش TABLE یا هر دو تغییر دهید، زیرا میزان استفاده هنوز در راهنما قابل مشاهده است. برای اطلاعات بیشتر، به بخش تغییر راهنمای کامل نمودار مراجعه کنید.

• ترافیک شما از API نقشه‌های جاسازی‌شده است. برای دستورالعمل‌ها، به تعیین APIهایی که از کلید API شما استفاده می‌کنند، مراجعه کنید.

• ترافیک برنامه یا وب‌سایت خارج از محدوده تاریخ موجود در مرورگر معیارهای کنسول Google Cloud است.

برای اعمال محدودیت‌های توصیه‌شده

1. صفحه اعتبارنامه‌های پلتفرم نقشه‌های گوگل (Google Maps Platform Credentials) در کنسول گوگل کلود (Google Cloud console) را باز کنید.

2. در صورت وجود، اعمال محدودیت‌های توصیه‌شده را انتخاب کنید.

   

3. برای تأیید اینکه کلید API در کدام سرویس‌ها استفاده می‌شود، گزینه «بررسی میزان استفاده از API» را انتخاب کنید. اگر سرویس‌هایی غیر از سرویس‌های پلتفرم نقشه‌های گوگل را مشاهده کردید، مکث کنید تا مراحل پیشنهادی بالا را به صورت دستی بررسی کنید. مراحل عیب‌یابی را در ابتدای بخش «اعمال محدودیت‌های کلید API توصیه‌شده» مشاهده کنید.

4. دوباره بررسی کنید که محدودیت‌های از پیش پر شده با وب‌سایت‌ها و برنامه‌هایی که انتظار دارید از کلید API شما در آنها استفاده شود، مطابقت داشته باشند.

   بهترین روش : هرگونه محدودیت برنامه یا API که به سرویس‌های شما وابسته نیست را مستندسازی و حذف کنید. اگر به دلیل وابستگی غیرمنتظره چیزی از کار افتاد، می‌توانید برنامه‌ها یا APIهای مورد نیاز را دوباره اضافه کنید.

   • اگر متوجه شدید که یک برنامه، وب‌سایت یا API به وضوح در پیشنهاد شما وجود ندارد، آن را به صورت دستی اضافه کنید یا چند روز صبر کنید تا پیشنهاد به‌روزرسانی شود.

   • اگر در مورد پیشنهاد پیشنهادی خود به کمک بیشتری نیاز دارید، با پشتیبانی تماس بگیرید .

5. اعمال را انتخاب کنید.

اگر درخواست شما پس از درخواست توصیه رد شود، چه باید کرد؟

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

SDKها و APIهای سمت کلاینت

برنامه‌های مبتنی بر مرورگر و وب‌ویو

مرورگرهای مدرن معمولاً به دلایل حفظ حریم خصوصی، هدر Referer در درخواست‌های بین مبدا حذف می‌کنند و اغلب آن را به Origin محدود می‌کنند. با این حال، رفتار دقیق آن به referrer-policy اعمال شده توسط سایت میزبان بستگی دارد و ممکن است بر اساس مرورگر و نسخه کاربر نیز متفاوت باشد.

برنامه‌های وب که از طرح‌های URI مبهم یا محلی برای بارگذاری محتوا استفاده می‌کنند، معمولاً مرورگر رندر یا نمای وب، هدر Referer از هرگونه فراخوانی خروجی کاملاً حذف می‌کنند، که ممکن است باعث شود درخواست‌ها با استفاده از کلیدهای API با محدودیت‌های وب‌سایت با شکست مواجه شوند.

برای راهنمایی بیشتر، به میزبانی برنامه‌های مبتنی بر مرورگر خود روی یک سرور مراجعه کنید.

دستورالعمل‌های عیب‌یابی برای برنامه‌های مبتنی بر مرورگر و وب‌ویو:

• برای API جاوا اسکریپت Maps، برای جزئیات بیشتر در مورد نحوه تأیید برنامه خود، به کنسول اشکال‌زدایی مرورگر مراجعه کنید.

  طرح‌های URI نامتعارف تا حدی پشتیبانی می‌شوند. اگر بخش‌هایی از برنامه شما حتی پس از تأیید ارجاع‌دهنده مورد نیاز، با طرح URI نامتعارف کار نکند، احتمالاً باید برنامه خود را از راه دور روی یک سرور میزبانی کنید و آن را از طریق HTTPS (یا HTTP) بارگذاری کنید.

  اگر در مورد طرح‌های URI نامتعارف به کمک نیاز دارید، با پشتیبانی تماس بگیرید .

• سایر APIهای پلتفرم نقشه‌ها معمولاً ارجاع‌دهنده‌ای را که باید در پاسخ خطای API تأیید کنید، برمی‌گردانند، با این فرض که کلاینت این اطلاعات را همراه با درخواست رد شده ارسال کرده است.

  طرح‌های URI نامتعارف پشتیبانی نمی‌شوند .

برنامه‌های اندروید

از Android Debug Bridge (adb) یا Logcat استفاده کنید

اپلیکیشن‌های iOS

مشاهده پیام‌های لاگ را ببینید

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

برای برنامه‌هایی که مستقیماً و بدون SDK پلتفرم نقشه‌های گوگل، HTTPS REST API یا نقاط انتهایی gRPC را فراخوانی می‌کنند، به زیر مراجعه کنید:

اپلیکیشن‌های اندروید و iOS

اگر برنامه اندروید یا iOS شما مستقیماً و بدون استفاده از هیچ یک از SDK های کلاینت موجود در پلتفرم نقشه‌های گوگل، سرویس‌های پلتفرم نقشه را فراخوانی می‌کند، برای نکات عیب‌یابی بیشتر به برنامه‌های اندروید و برنامه‌های iOS مراجعه کنید و برای بهترین شیوه‌های امنیتی فعلی برای موارد استفاده موبایل، به Secure client-side web service مراجعه کنید .

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

برنامه‌های سمت سرور

برنامه‌های سمت سرور که به کلیدهای API متکی هستند، از طریق محدودیت‌های آدرس IP به بهترین شکل ایمن می‌شوند. اگر محدودیت‌های آدرس IP را برای کلید خود اعمال کرده‌اید و سرویس شما پاسخ‌های خطای API پلتفرم نقشه‌ها را ثبت می‌کند، برای اطلاعات بیشتر، گزارش‌های سیستم خود را بررسی کنید. پاسخ خطا شامل آدرس IP سروری است که باید آن را مجاز کنید.

برنامه‌های مبتنی بر مرورگر یا وب‌ویو

اگرچه API استاتیک Maps، API استاتیک Street View و APIهای جدیدتر پلتفرم Google Maps نیز از محدودیت‌های ارجاع‌دهنده پشتیبانی می‌کنند، توجه داشته باشید که مرورگرهای وب یا وب‌ویوها احتمالاً هدر Referer برای درخواست‌های بین‌منبعی به Origin محدود می‌کنند و احتمالاً از ارسال کامل آن، مثلاً برای منابع محلی یا برای منابعی که از طریق پروتکل‌هایی غیر از HTTP یا HTTPS ارائه می‌شوند، خودداری می‌کنند.

اگر نمی‌توانید از Maps JavaScript API در برنامه خود استفاده کنید و محدودیت‌های وب‌سایت کار نمی‌کنند، برای نحوه‌ی فراخوانی ایمن وب سرویس پلتفرم Maps از درون برنامه‌ی سمت کلاینت مبتنی بر مرورگر خود، به بخش «فراخوانی‌های وب سرویس سمت کلاینت امن» مراجعه کنید.

نکاتی برای بررسی محدودیت‌های API

برای بررسی محدودیت‌های API مورد نیاز خود، به بخش «تعیین APIهایی که از کلید API شما استفاده می‌کنند» مراجعه کنید.

اگر نمی‌توانید تعیین کنید که کدام محدودیت‌ها را باید اعمال کنید:

1. محدودیت‌های فعلی را برای مراجعات بعدی مستند کنید.
2. آنها را موقتاً حذف کنید تا مشکل را بررسی کنید. می‌توانید با استفاده از مراحل موجود در بخش «استفاده از کلید API خود را بررسی کنید»، میزان استفاده خود را در طول زمان بررسی کنید.
3. در صورت نیاز، با پشتیبانی تماس بگیرید .

کلیدهای API استفاده نشده را حذف کنید

قبل از حذف کلید API، مطمئن شوید که در محیط عملیاتی استفاده نمی‌شود. اگر هیچ ترافیک موفقیت‌آمیزی وجود ندارد، احتمالاً حذف کلید بی‌خطر است. برای اطلاعات بیشتر، به «بررسی میزان استفاده از کلید API» مراجعه کنید.

برای حذف کلید API:

1. صفحه اعتبارنامه‌های پلتفرم نقشه‌های گوگل (Google Maps Platform Credentials) در کنسول گوگل کلود (Google Cloud console) را باز کنید.

2. کلید API مورد نظر برای حذف را انتخاب کنید.

3. دکمه حذف را در نزدیکی بالای صفحه انتخاب کنید.

4. در صفحه حذف اعتبارنامه ، گزینه حذف را انتخاب کنید.

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

هنگام چرخاندن کلیدهای API مراقب باشید

چرخاندن یک کلید API، یک کلید جدید ایجاد می‌کند که تمام محدودیت‌های کلید قدیمی را دارد. در طول این بازه زمانی، هر دو کلید قدیمی و جدید پذیرفته می‌شوند و به شما این فرصت را می‌دهند که برنامه‌های خود را برای استفاده از کلید جدید منتقل کنید.

قبل از چرخاندن کلید API :

• ابتدا سعی کنید کلیدهای API خود را همانطور که در بخش «محدود کردن کلیدهای API» توضیح داده شده است، محدود کنید.

• اگر محدود کردن کلید API شما به دلیل انواع محدودیت‌های متناقض برنامه امکان‌پذیر نیست، همانطور که در بخش «مهاجرت به چندین کلید API» توضیح داده شده است، به چندین کلید جدید (محدود شده) مهاجرت کنید. مهاجرت به شما امکان می‌دهد مهاجرت را کنترل کنید و جدول زمانی را به کلیدهای API جدید اعمال کنید.

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

1. صفحه اعتبارنامه‌های پلتفرم نقشه‌های گوگل (Google Maps Platform Credentials) در کنسول گوگل کلود (Google Cloud console) را باز کنید.

2. کلید API مورد نظر برای چرخش را باز کنید.

3. در بالای صفحه، کلید چرخش (Rotate key) را انتخاب کنید.

4. در صورت تمایل، نام کلید API را تغییر دهید.

5. ایجاد را انتخاب کنید.

6. برنامه‌های خود را برای استفاده از کلید جدید به‌روزرسانی کنید.

پس از اینکه برنامه‌های خود را برای استفاده از کلید جدید به‌روزرسانی کردید، با کلیک بر روی دکمه‌ی «حذف کلید قبلی» در بخش «کلید قبلی» در صفحه‌ی کلید API جدید، کلید قدیمی را حذف کنید.

به چندین کلید API مهاجرت کنید

برای تغییر از استفاده از یک کلید API برای چندین برنامه به یک کلید API منحصر به فرد برای هر برنامه، موارد زیر را انجام دهید:

1. مشخص کنید کدام برنامه‌ها به کلیدهای جدید نیاز دارند :

   • به‌روزرسانی برنامه‌های وب آسان‌ترین روش است، زیرا شما تمام کد را کنترل می‌کنید. برای به‌روزرسانی کلیدهای تمام برنامه‌های تحت وب خود برنامه‌ریزی کنید.
   • برنامه‌های تلفن همراه بسیار سخت‌تر هستند، زیرا مشتریان شما باید برنامه‌های خود را قبل از استفاده از کلیدهای جدید به‌روزرسانی کنند.

2. ایجاد و محدود کردن کلیدهای جدید : هم یک محدودیت برنامه و هم حداقل یک محدودیت API اضافه کنید. برای اطلاعات بیشتر، به بهترین شیوه‌های توصیه‌شده مراجعه کنید.

3. کلیدهای جدید را به برنامه‌های خود اضافه کنید : برای برنامه‌های تلفن همراه، این فرآیند ممکن است ماه‌ها طول بکشد تا همه کاربران شما به آخرین برنامه با کلید API جدید به‌روزرسانی کنند.

تقسیم استفاده از سمت کلاینت و سمت سرور به پروژه‌های جداگانه

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

این رویکرد به شما امکان می‌دهد محدودیت‌های سهمیه‌ای مناسب برای هر دقیقه و هر کاربر را در اکثر سرویس‌های پلتفرم نقشه‌های گوگل در پروژه سمت کلاینت خود اعمال کنید و به شما کمک می‌کند تا مطمئن شوید که همه کاربران نهایی سهم منصفانه‌ای از سهمیه کلی پروژه شما را بدون تأثیر بر یکدیگر دریافت می‌کنند.

با این حال، از آنجایی که محدودیت‌های سهمیه هر کاربر، هم برنامه‌های سمت کلاینت و هم برنامه‌های سمت سرور را تحت تأثیر قرار می‌دهد، اگر برای کارهای سمت سرور خود به پهنای باند بالایی نیز نیاز دارید، یک پروژه جداگانه برای این مورد استفاده تنظیم کنید که با محدودیت سهمیه هر کاربر بالاتر پیکربندی شده باشد یا اصلاً هیچ محدودیتی نداشته باشد.

غیرفعال کردن سرویس‌های بلااستفاده

سرویس‌های بلااستفاده را در یک پروژه فعال نگذارید، زیرا این روش در برابر سوءاستفاده آسیب‌پذیر است، به خصوص اگر تمام کلیدهای API عمومی خود را محدود نکرده باشید. به عنوان یک روش بهتر، فقط زمانی یک سرویس را در یک پروژه فعال کنید که برنامه‌های شما به آن نیاز داشته باشند.

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

استفاده از SDK های سمت کلاینت

هنگام استفاده از SDK های ارائه شده سمت کلاینت پلتفرم نقشه های گوگل، شما همیشه قادر خواهید بود محدودیت های مناسبی را برای کلید API خود اعمال کنید تا استفاده از سرویس خود را ایمن کنید.

استفاده از SDK های سمت کلاینت همچنین به شما امکان می‌دهد مکانیسم امنیتی پیشرفته‌تری مانند Firebase App Check را روی سطوح API پلتفرم Maps که از آن پشتیبانی می‌کنند، اتخاذ کنید. برای جزئیات بیشتر به بخش «استفاده از App Check برای ایمن‌سازی کلید API» مراجعه کنید.

اگر SDK های سمت کلاینت برای پلتفرم شما در دسترس نیستند، به بخش «امن‌سازی فراخوانی‌های سرویس وب سمت کلاینت» مراجعه کنید.

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

محافظت از استفاده از API وب استاتیک

APIهای وب استاتیک، مانند API استاتیک نقشه‌ها و API استاتیک نمای خیابان، مشابه فراخوانی‌های API سرویس وب هستند.

شما هر دو را با استفاده از یک HTTPS REST API فراخوانی می‌کنید و معمولاً URL درخواست API را روی سرور ایجاد می‌کنید. با این حال، به جای بازگرداندن پاسخ JSON، APIهای وب استاتیک تصویری تولید می‌کنند که می‌توانید آن را در کد HTML تولید شده جاسازی کنید. مهمتر از همه، معمولاً این کلاینت کاربر نهایی است، نه سرور، که سرویس پلتفرم نقشه‌های گوگل را فراخوانی می‌کند.

استفاده از امضای دیجیتال

به عنوان یک روش بهینه، همیشه علاوه بر کلید API از امضاهای دیجیتال نیز استفاده کنید. همچنین، بررسی کنید که می‌خواهید روزانه چند درخواست امضا نشده مجاز باشد و سهمیه درخواست‌های امضا نشده خود را بر اساس آن تنظیم کنید .

برای جزئیات بیشتر در مورد امضاهای دیجیتال، به راهنمای امضای دیجیتال مراجعه کنید.

از راز امضای خود محافظت کنید

برای محافظت از APIهای وب استاتیک، رمزهای امضای API خود را مستقیماً در کد یا در درخت منبع جاسازی نکنید، یا آنها را در برنامه‌های سمت کلاینت نمایش ندهید. برای محافظت از رمزهای امضای خود، این بهترین شیوه‌ها را دنبال کنید:

• هنگام ارائه یک صفحه وب یا در پاسخ به درخواستی از برنامه تلفن همراه خود، URL های درخواست Maps Static API و Street View Static API امضا شده خود را در سمت سرور ایجاد کنید .

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

  برای محتوای وب پویا، به نمونه‌های کد امضای درخواست URL موجود مراجعه کنید.

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

محافظت از کلیدهای API سرویس وب

For secure use of Google Maps Platform APIs and services from client-side apps, see Use client-side SDKs and Secure client-side web service calls .

Store API keys outside of your application's source code or source tree . If you put your API keys or any other information in environment variables or include files that are stored separately and then share your code, the API keys are not included in the shared files. This is particularly important if you use a public source code management system, such as GitHub.

To help shield your web service API key against accidental use, Google recommends applying API restrictions to any key used for Maps Platform. Furthermore, also applying IP address restrictions to your web service key will protect it against help protect it against unauthorized use from other source IP addresses, even if the key accidentally leaks.

Use OAuth for server-side apps

OAuth 2.0 is an open standard for access delegation.

While the OAuth 2.0 protocol supports use cases, where an end user authorizes an application to access personal data on their behalf, the intended use case for OAuth 2.0 with Maps Platform is for the developer to utilize temporary access tokens for authorizing their application to call an API on behalf of their Google Cloud project service account with the permissions of the service account.

As a service account may have extremely broad permissions, OAuth 2.0 is recommended for authorizing server-to-server calls between a developer's trusted server-side applications and Google's Maps Platform servers.

For client-side applications running on end user devices, other authentication methods, such as API keys, are recommended.

If you want to use OAuth 2.0 to authorize server-to-server traffic, look for the OAuth topic in your API documentation.

For example, here is the OAuth topic for the Address Validation API .

Secure client-side web service calls

If client-side SDKs are not available, see the recommendations below.

از یک سرور پروکسی استفاده کنید

Using a secure proxy server provides a solid source for interacting with a Google Maps Platform web service endpoint from a client-side application without exposing your API key, signing secret or Google Cloud service account to unauthorized users.

نکات کلیدی:

• Construct your Google Maps Platform requests on the proxy server. Don't allow clients to relay arbitrary API calls using the proxy.

• Post-process the Google Maps Platform responses on your proxy server. Filter out data that the client doesn't need.

For more information about using a proxy server, see Living Vicariously: Using Proxy Servers with the Google Data API Client Libraries .

Secure direct mobile web service calls

If you are unable to set up a secure proxy server for your client-side app, secure your application using the following steps:

1. Use HTTP headers:

   • Android : Use the X-Android-Package and X-Android-Cert HTTP headers.

   • iOS : Use the X-Ios-Bundle-Identifier HTTP header.

2. Add the corresponding application restrictions to your Android or iOS key.

3. Before you consider issuing calls directly from your mobile application to a Google Maps Platform REST API web service, verify that requests with incorrect Android or iOS application identifiers are rejected.

   If Android and iOS application restrictions are not supported on the tested endpoint, Google strongly recommends that you use a secure proxy server between your mobile clients and the Google Maps Platform web service endpoint.

Tips for Android applications:

• Before you integrate your Android application with Google Maps Platform services, verify that your application ID (also called package name) is formatted correctly. For details, see Configure app module . in the Android documentation.

• To pass X-Android-Package directly from your application, look it up programmatically using Context.getPackageName() .

• To pass X-Android-Cert directly from your applications, calculate the required SHA-1 fingerprint of your application signing certificates, accessible through PackageInfo.signingInfo .

• If you authorize your Android application using the Google Cloud console, note that the UI expects the SHA-1 fingerprint to be a colon-delimited string, eg, 00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33 . However, the gcloud tool and the API keys API expect the hexadecimal string without delimiters.

Tips for iOS applications:

• Before you integrate your iOS application with Google Maps Platform services, verify that your Bundle ID is formatted correctly .

• You should typically always pass the Bundle ID of your main bundle in the X-Ios-Bundle-Identifier header, when authorizing your iOS application.

For further information, refer to articles Manage API keys and Use API keys to access APIs .

Host your browser based apps on a server

Frameworks, such as Apache Cordova, allow you to conveniently create multi-platform hybrid apps running inside a webview. However, API key website restrictions are not guaranteed to work correctly, unless your web app is loaded using HTTP or HTTPS from a website that you control and have authorized.

Bundled resources, loaded locally from within a hybrid application, or accessed using a local file URL will in many cases prevent referrer based authorization from working as the browser engine powering your webview will omit sending the Referer header. To avoid this, host your web applications server-side, not client-side.

Alternatively, for mobile applications, consider using available native Google Maps Platform Android and iOS SDKs, instead of using a web based SDK.

برای ایمن‌سازی کلید API خود از App Check استفاده کنید

Certain Maps SDKs and APIs allow you to integrate with Firebase App Check . App Check provides protection for calls from your app to Google Maps Platform by blocking traffic that comes from sources other than legitimate apps. It does this by checking for a token from an attestation provider. Integrating your apps with App Check helps to protect against malicious requests, so you're not charged for unauthorized API calls.

App Check integration instructions:

• SDK مکان‌ها برای iOS
• SDK مکان‌ها برای اندروید
• API جاوا اسکریپت نقشه‌ها
• Place class, Maps JavaScript API

Handle unauthorized use of an API key

If you detect use of your API key that is unauthorized, do the following to address the problem:

1. Restrict your keys : If you've used the same key in multiple apps, migrate to multiple API keys, and use separate API keys for each app. For more details, see:

   • Restrict your API keys
   • Migrate to multiple API keys
   • Use separate API keys for each app

2. If you use the Places SDK or the Maps Javascript API, you can also use App Check to secure your API Key .

3. Only replace or rotate keys if the following is true:

   • You detect unauthorized usage on keys that either cannot be restricted or are already restricted, and App Check is not applicable.

   • You want to move more quickly to secure your API key and stop the abuse, even if it might impact legitimate traffic from your application.

   Before proceeding, read through Be careful when rotating API keys .

4. If you are still having issues or need help, contact support .

Recommended application and API restrictions

The following sections suggest appropriate application and API restrictions for each Google Maps Platform API, SDK or service.

Recommended API Restrictions

The following guidelines for API restrictions apply to all Google Maps Platform services:

• Restrict your API key to only the APIs you are using it for, with the following exceptions:

  • If your app uses the Places SDK for Android or Places SDK for iOS, authorize Places API (New) or Places API, depending on the SDK versions you use. ¹

  • If your app uses Maps JavaScript API, always authorize it on your key.

  • If you also use any of the following Maps JavaScript API services, you should also authorize these corresponding APIs:

    خدمات	API restriction
    Directions Service (Legacy)	Directions API (Legacy)
    Distance Matrix Service (Legacy)	Distance Matrix API (Legacy)
    خدمات ارتفاع	API ارتفاع
    سرویس ژئوکدینگ	API کدگذاری جغرافیایی
    Place class, Place Autocomplete Widget (New) & Place Autocomplete Data API	Places API (New) 2
    Places Library, Places Service & Place Autocomplete Widget	Places API 2

¹ For more details, see the Places SDK for Android and Places SDK for iOS documentation.

² If you are unsure if you need to authorize Places API (New) or Places API, see the Maps JavaScript API documentation.

چند مثال:

• You are using the Maps SDK for Android and Places SDK for Android, so you include the Maps SDK for Android and Places API (New) as API restrictions.

• Your website uses the Maps JavaScript API Elevation Service and the Maps Static API, so you add API restrictions for all of the following APIs:

  • API جاوا اسکریپت نقشه‌ها
  • API ارتفاع
  • API استاتیک نقشه‌ها

Recommended application Restriction

وب‌سایت‌ها

For websites using Maps JavaScript API services, Maps Static API or Street View Static API or calling recent Google Maps Platform services directly over the HTTPS REST API or gRPC, use the Websites application restriction:

Directions Service (Legacy) Distance Matrix Service (Legacy) خدمات ارتفاع سرویس ژئوکدینگ

Maps JavaScript API 1 Places Library 2 Maps Static API 3 Street View Static API 3

¹ For mobile applications, consider using the native Maps SDK for Android and Maps SDK for iOS .

² For mobile applications, consider using the native Places SDK for Android and Places SDK for iOS .

³ See also Protect Static Web API usage .

Websites with the Maps Embed API

While using the Maps Embed API is no charge, you should still restrict any used API key to prevent abuse on other services.

Best practice : Create a separate API key for Maps Embed API use, and restrict this key to only the Maps Embed API. This restriction sufficiently secures the key, preventing its unauthorized use on any other Google service. For full control over where your Maps Embed API key can be used from, Google recommends also applying Websites application restrictions.

If you are unable to separate your Maps Embed API usage to a separate API key, secure your existing key using the Websites application restriction.

Apps and servers using web services

For servers and client-side apps from trusted corporate internal networks using web services together with API keys, use the IP addresses application restriction.

Use for apps and servers using these APIs:

API اعتبارسنجی آدرس API نمای هوایی کیفیت هوا (Air Quality API) Directions API (Legacy) 4 Distance Matrix API (Legacy) 4 API ارتفاع Geocoding API 5 Geolocation API 6 API کاشی‌های نقشه

API مجموعه داده‌های نقشه‌ها Places API (New) 7 Places API 6 API جاده‌ها Routes API 4 Pollen API API خورشیدی Time Zone API 8 رابط برنامه‌نویسی کاربردی آب و هوا

⁴ For mobile applications, consider using the Navigation SDK.

⁵ For safe mobile usage, use a secure proxy server .

⁶ For client-side applications, consider using the native geolocation service offered by the platform; for example, W3C Geolocation for web browsers, LocationManager or the Fused Location Provider API for Android, or the Apple Core Location framework for iOS.

⁷ For mobile applications, consider using the native Places SDK for Android and Places SDK for iOS .

⁸ For safe client-side usage, use a secure proxy server .

برنامه‌های اندروید

For apps on Android, use the Android apps application restriction. Use for apps using these SDKs:

• SDK نقشه‌ها برای اندروید
• SDK مکان‌ها برای اندروید
• SDK ناوبری برای اندروید

In addition, prevent accidentally checking API keys into version control by using the Secrets Gradle Plugin to inject secrets from a local file rather than storing them in the Android Manifest.

اپلیکیشن‌های iOS

For apps on iOS, use the iOS apps application restriction. Use for apps and servers using these SDKs:

• SDK نقشه برای iOS
• SDK مکان‌ها برای iOS
• کیت توسعه نرم‌افزار ناوبری برای iOS

مطالعه بیشتر

• مدیریت کلیدهای API
• Use API keys to access APIs
• Optimize your Google Maps Platform usage with quotas (video)
• How to generate and restrict API keys for the Google Maps Platform (video)
• Restricting API keys
• Securing API keys when using Static Maps and Street View APIs
• 15 Google Maps platform Best Practices

،

Apps and projects that use the Google Maps Platform APIs and SDKs must use API keys or, if supported, OAuth 2.0, to authenticate themselves.

These best practices show you how to secure your Maps Platform access.

If you want to use OAuth 2.0 to authorize server-to-server traffic, look for the OAuth topic in your API documentation. See Use OAuth for server-side apps for more details.

In addition to applying application and API key restrictions, follow any security practices that apply to specific Google Maps Platform products. For example, see the Maps JavaScript API below in Recommended application and API restrictions .

If your API keys are already in use, review the recommendations below in If you are restricting an API key that's in use .

For more details about digital signatures, supported by Maps Static API and Street View Static API, see the Digital Signature Guide .

Recommended best practices

For increased security and to avoid being billed for unauthorized use, follow these API security best practices for all Google Maps Platform APIs, SDKs, or services:

Recommended for all API key uses

Restrict your API keys

Use separate API keys for each app

Delete unused API keys

Check your API key usage

Be careful when rotating API keys

Split client-side and server-side usage into separate projects

Disable unused services

Additional recommendations for client-side apps

Use client-side SDKs

Secure client-side web service calls

Additional recommendations for websites or client-side apps using Static Web APIs

Protect Static Web API usage

Additional recommendations for server-side apps using web services

Protect web service API keys

Use OAuth for server-side apps

If you are restricting or rotating an API key that's in use

• Before you change the API key, Check your API key usage This step is especially important if you are adding restrictions for a key that is already in use in a production application.

• After you change the key, update all of your apps with the new API keys, as needed.

• If your API key has not been compromised and is not actively abused, you can migrate your apps to multiple new API keys at your own pace, leaving the original API key untouched until you only observe one type of traffic, and the API key can safely be restricted with a single type of application restrictions without causing unintended service disruptions.

  For further instructions, see Migrate to multiple API keys .

  Monitor the usage over time, and see when specific APIs, platform types, and domains have migrated off the old API key before you choose to restrict or delete the old key. For more information, see Reporting and monitoring and Metrics

• If your API key has been compromised, you want to move more quickly to secure your API key and stop the abuse. In Android and iOS apps, keys aren't replaced until customers update their apps. Updating or replacing keys in on webpages or in server-side apps is much more straightforward, but may still require careful planning and fast work.

  For more information, see Handle unauthorized use of an API key .

اطلاعات بیشتر

Recommended application and API restrictions

Restrict your API keys

Best practice is to always restrict your API keys with one type of application restrictions and one or more API restrictions. For suggested restrictions by API, SDK, or JavaScript service, see Recommended application and API restrictions below.

• Application restrictions You can limit the use of an API key to specific platforms: Android or iOS applications, or specific websites for client-side applications, or specific IP addresses or CIDR subnets for server-side apps issuing web service REST API calls.

  You restrict a key by adding one or more application restrictions of the types you want to authorize, after which only requests originating from these sources are permitted.

• API restrictions You can restrict which Google Maps Platform APIs, SDKs, or services on which your API key can be used. API restrictions only allow requests to the APIs and SDKs you specify. For any given API key, you can specify as many API restrictions as needed. The list of available APIs includes all APIs enabled on a project.

Set an application restriction for an API key

1. Open the Google Cloud console Google Maps Platform Credentials page.

2. Select the API key that you want to restrict.

3. On the Edit API key page , under Key restrictions , select Set an application restriction .

   

4. Select one of the restriction types and supply the requested information following the restriction list.

   Restriction type	توضیحات
   وب‌سایت‌ها	Specify one or more referrer websites. The universally supported referrer URI schemes are https and http . Other schemes are not guaranteed to work correctly, since modern web browsers will for privacy reasons not send a `Referer` header in outgoing requests. Always provide the whole referrer string, including the protocol scheme, hostname and optional port (eg, https://google.com ). You can use wildcard characters to authorize all subdomains. For example, https://*.google.com accepts all sites ending in .google.com . Be careful when authorizing full-path referrers, for example, https://google.com/some/path , since most web browsers will for privacy reasons strip the path from cross-origin requests.
   آدرس‌های IP	Specify one or more IPv4 or IPv6 addresses, or subnets using CIDR notation. The IP addresses must match the source address the Google Maps Platform servers observe. If you use network address translation (NAT) , this address typically corresponds to your machine's public IP address.
   برنامه‌های اندروید	Add the Android package name (from the AndroidManifest.xml file) and the SHA-1 signing certificate fingerprint of each Android application you want to authorize. Select Android apps . Click + Add . Enter your package name and SHA-1 certificate fingerprint. For example: com.example.android.mapexample BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75 روی ذخیره کلیک کنید. There are two certificate types: Debug certificate : Only use this certificate type with apps you're testing and other non-production code. Don't attempt to publish an app that's signed with a debug certificate. The Android SDK tools generate this certificate automatically when you run a debug build. Release certificate : Use this certificate when you're ready to release your app to an app store. The Android SDK tools generate this certificate when you run a release build. For more information about Android application signing and certificates, see the Sign your app guide . If you use Play App Signing , to fetch the signing certificate fingerprint, see Working with API Providers . If you manage your own signing key, see Self-signing your application or refer to the instructions for your build environment.
   اپلیکیشن‌های iOS	Add the bundle identifier of each iOS application you want to authorize. Select iOS apps . Click + Add . Add the bundle ID to accept requests from the iOS app with that ID. روی ذخیره کلیک کنید.

   For recommendations for an application restriction, see Recommended application Restriction .

5. ذخیره را انتخاب کنید.

تنظیم محدودیت‌های API برای یک کلید API

1. Open the Google Cloud console Google Maps Platform Credentials page.

2. Select the API key that you want to restrict.

3. On the Edit API key page , under API restrictions :

   • Select Restrict key .

   • Open Select APIs and select the APIs or SDKs you want your application to access using the API key.

   If an API or SDK is not listed, you need to enable it. For details, see To enable one or more APIs or SDKs .

   

4. ذخیره را انتخاب کنید.

   The restriction becomes part of the API key definition after this step. Be sure you provide the appropriate details and select Save to save your API key restrictions. For further information, see the Get an API Key guide in the documentation for the specific API or SDK you are interested in.

For recommended API restrictions, see Recommended API Restrictions .

Check your API key usage

If you're restricting API keys after they've been created, or if you want to see what APIs are being used by a key so you can restrict them, you want to check your API key usage. These steps show you in which services and API methods an API key is being used. If you see any usage beyond Google Maps Platform services, investigate to determine if you need to add more restrictions to avoid unwanted use. You can use the Google Maps Platform Cloud Console Metrics explorer to help determine which API and application restrictions to apply to your API key:

• Determine the APIs that use your API key

• Choose the correct type of application restriction using the Metrics explorer

Determine the APIs that use your API key

The following metrics reports allow you to determine which APIs are using your API keys. Use these reports to do the following:

• See how your API keys are used
• Spot unexpected usage
• Help verify if an unused key is safe to delete. For information about deleting an API key, see Delete unused API keys .

When applying API restrictions, use these reports to create a list of APIs to authorize, or to validate automatically-generated API key restriction recommendations. For more information about recommended restrictions, see Apply recommended restrictions . For more information about using the Metrics explorer, see Create charts with Metrics explorer .

1. Go to the Google Cloud console's Metrics explorer

2. Sign in and select the project for the API keys you want to check.

3. Go to the Metrics explorer page for your type of API:

   • For API keys using any API except the Maps Embed API : Go to Metrics explorer page.

   • For API keys using Maps Embed API : Go to Metrics Explorer .

4. Inspect each API key:

   1. Select ADD FILTER .

   2. Select the label credential_id .

   3. Select the value corresponding to the key you want to inspect.

   4. Note which APIs this API key is being used for, and confirm the use is expected.

   5. Once done, select Remove filter delete at the end of the active filter line to delete the extra filter.

5. Repeat for any remaining keys.

6. Restrict your API keys to only the APIs that are being used.

7. If you spot unauthorized use, see Handle unauthorized use of an API key .

Choose the correct type of application restriction using the Metrics explorer

After you have verified and taken any needed actions to make sure your API key is only used for the Google Maps Platform services it is using, also verify the API key has the correct application restrictions.

If your API key has recommended API key restrictions, apply them. For more information, see Apply recommended API key restrictions .

If your API key doesn't have restriction recommendations, determine the type of application restriction to apply, based on the reported platform_type using the Metrics explorer:

1. Go to the Google Cloud console's Metrics explorer

2. Sign in and select the project for the APIs you want to check.

3. Go to this Metrics explorer page: Metrics explorer .

4. Inspect each API key:

   1. Select ADD FILTER .

   2. Select the label credential_id .

   3. Select the value corresponding to the key you want to inspect.

   4. Once done, select Remove filter delete at the end of the active filter line to delete the extra filter.

5. Repeat for any remaining keys.

6. Once you have the platform type for your API keys, apply the application restriction for that platform_type :

   PLATFORM_TYPE_JS : Apply Website restrictions on the key.

   PLATFORM_TYPE_ANDROID : Apply Android application restrictions on the key.

   PLATFORM_TYPE_IOS : Apply iOS application restrictions on the key.

   PLATFORM_TYPE_WEBSERVICE : You may have to rely on IP address restrictions on the key, to properly restrict it.

   For recommendations for Maps Static API and Street View Static API, see Protect Static Web API usage .

   For Maps Embed API recommendations, see Websites with the Maps Embed API .

   My API key is using multiple platform types: Your traffic can't be properly secured with just a single API key. You need to migrate to multiple API keys. For more information, see Migrate to multiple API keys .

Use separate API keys for each app

This practice limits the scope of each key. If one API key is compromised, you can delete or rotate the impacted key without needing to update your other API keys. You can create up to 300 API keys per project. For more information, see Limits on API keys .

While one API key per application is ideal for security purposes, you can use restricted keys on multiple apps as long as they use the same type of application restriction.

Apply recommended API key restrictions

For some project owners, editors and API key administrators, the Google Cloud console suggests specific API key restrictions to unrestricted API keys based on their Google Maps Platform usage and activity.

If available, recommendations appear as pre-filled options on the Google Maps Platform Credentials page.

Google Maps Platform APIs and SDKs supported by the automated recommendations

• Maps JavaScript API, including Directions Service (Legacy), Distance Matrix Service (Legacy), Elevation Service, Geocoding Service Place class, Place Autocomplete Widget (New), Place Autocomplete Data API, Places Library, Places Service, Place Autocomplete Widget, and Places UI Kit

• Maps Static API and Street View Static API

• API جاسازی نقشه‌ها

• Maps SDK for Android, Navigation SDK for Android, Places SDK for Android, and Places UI Kit on Android

• Maps SDK for iOS, Navigation SDK for iOS, Places SDK for iOS, Places Swift SDK for iOS, and Places UI Kit on iOS.

Reasons you may not see a recommendation, or an incomplete one

Reasons for seeing no recommendation

• You are (also) using the API key on other than Google Maps Platform services, or or Maps Platform services that are not yet supported by the automatic recommendations.

  If you see usage on other services, don't apply the recommendation without first doing the following:

  1. Verify that the API usage you see in the Google Cloud console Metrics explorer is legitimate.

  2. Manually add missing services to the list of APIs to be authorized.

  3. Manually add any missing application restrictions for the services added to the API list. If your other added would require a different type of application restrictions, see Migrate to multiple API keys .

• Your API key is not used in client-side SDKs or APIs.

• You use the API key in a low-volume app or website that has not seen usage over the last 60 days.

• You have created a new key very recently, or you have very recently deployed an existing key in a new app. If this is the case, just wait a few more days to allow the recommendations to update.

• You are using the API key in multiple applications that would require conflicting types of application restrictions, or you are using the same API key in too many different apps or websites. In either case, as a best practice, you should migrate to multiple keys. For more details, see Migrate to multiple API keys .

Reasons for seeing an incomplete recommendation

• You use the API key in a low-volume app or website that has not seen usage over the last 60 days.

• You have very recently started using a existing key on a new API or service, and the automatic API key restriction recommendation pipeline, has not yet processed the updated usage metrics. The propagation of usage metrics may take a few days.

  If you see usage on other services, don't apply the recommendation without first doing the following:

  1. Verify that the API usage you see in the Google Cloud console Metrics explorer is legitimate.

  2. Manually add missing services to the list of APIs to be authorized.

  3. Manually add any missing application restrictions for the services added to the API list. If your other added would require a different type of application restrictions, see Migrate to multiple API keys .

  4. Unless you urgently need to restrict a key, for example, due to unauthorized use, you might also wait a day or two for the recommendations to catch up.

Reasons you might see recommendations that are not visible in the charts

• Your app or website sent only very short traffic bursts. In this case, switch from a CHART view to display a TABLE or BOTH , as the usage is still visible in the legend. For more information, see Toggling the chart's full legends .

• Your traffic is from the Maps Embed API. For instructions, see Determine the APIs that use your API key .

• The traffic from the app or website is outside the date range available in the Google Cloud console Metrics explorer.

To apply recommended restrictions

1. Open the Google Cloud console Google Maps Platform Credentials page.

2. If available, select Apply recommended restrictions .

   

3. Select Check API usage to verify which services the API key is being used on. If you see other than Google Maps Platform services, pause to manually review the recommendation steps above. See the troubleshooting steps at the beginning of section Apply recommended API key restrictions .

4. Double-check that the pre-filled restrictions match the websites and apps where you expect to use your API key.

   Best Practice : Document and remove any application or API restrictions that are not affiliated with your services. If something breaks due to an unexpected dependency, then you can add the required apps or APIs back in.

   • If you recognize that an app, website or API is clearly missing from your recommendation, add it manually or wait a couple of days to allow the recommendation to update.

   • If you need further help with your suggested recommendation, contact support .

5. اعمال را انتخاب کنید.

What to do if your application gets rejected after applying a recommendation

If you notice that an app or website gets rejected after applying a restriction, look for the application restriction you need to add in the API response error message.

Client-side SDKs and APIs

Browser and webview based apps

Modern browsers typically redact the Referer header in cross-origin request for privacy reasons, often stripping it down to the Origin . However, the exact behavior depends on the applied referrer-policy of the hosting site, and may also vary, based on the user browser and version.

Web applications using opaque or local URI schemes for loading content will typically have the rendering browser or webview completely redact the Referer header from any outgoing calls, which may cause requests to fail using API keys with website restrictions.

For further guidance, see Host your browser based apps on a server .

Troubleshooting instructions for browser and webview based apps:

• For Maps JavaScript API, see the browser debug console for details on how to authorize your application.

  Exotic URI schemes are partially supported. If parts of your application don't work it an exotic URI scheme, even after authorizing the required referrer, you will likely need to host your application remotely on a server and load it over HTTPS (or HTTP).

  If you need help with exotic URI schemes, contact support .

• Other Maps Platform APIs will generally return the referrer you need to authorize in the API error response, presuming the client sent this information with the rejected request.

  Exotic URI schemes are not supported.

برنامه‌های اندروید

Use Android Debug Bridge (adb) or Logcat

اپلیکیشن‌های iOS

See Viewing Log Messages

Apps calling web services directly

For applications calling Maps Platform HTTPS REST API or gRPC endpoints directly without a client-side Google Maps Platform SDK, see below:

اپلیکیشن‌های اندروید و iOS

If your Android or iOS application calls Maps Platform services directly without using any of the available Google Maps Platform client SDKs, see Android apps and iOS apps for further troubleshooting tips, and Secure client-side web service calls for current best security practices for mobile use cases.

If your app logs Maps Platform API error responses, the above instructions for client-side SDKs may also prove useful for troubleshooting authentication issues.

Server-side apps

Server-side applications relying on API keys are best secured through IP address restrictions. If you have applied IP address restrictions to your key, and your service logs Maps Platform API error responses, check your system logs for further information. The error response will include the server IP address that you need to authorize.

Browser or webview based apps

While Maps Static API, Street View Static API more recent Google Maps Platform APIs will also support referrer restrictions, note that web browsers or webviews will likely restrict the Referer header to the Origin for cross-origin requests, and will likely omiy sending it altogether, eg, for locally accessed resources, or for resources served over protocols other than HTTP or HTTPS.

If you can't use Maps JavaScript API in your application, and website restrictions don't work, see Secure client-side web service calls for how to issue Maps Platform web service calls securely from within your browser based client-side application.

Tips for checking API restrictions

To check your required API restrictions, see Determine the APIs that use your API key .

If you are unable to determine which restrictions to apply:

1. Document the current restrictions for future reference.
2. Remove them temporarily while you investigate the issue. You can check your usage over time using the steps in Check your API key usage .
3. If needed, contact support .

Delete unused API keys

Before you delete an API key, make sure that it is not used in production. If there is no successful traffic, the key is likely safe to delete. For more information, see Check your API key usage .

To delete an API key:

1. Open the Google Cloud console Google Maps Platform Credentials page.

2. Select the API key you want to delete.

3. Select the Delete button near the top of the page.

4. On the Delete credential page, select Delete .

   Deleting an API key takes a few minutes to propagate. After propagation completes, any traffic using the deleted API key is rejected.

Be careful when rotating API keys

Rotating an API key creates a new key that has all the old key's restrictions. During this time window, both the old and new key are accepted, giving you a chance to migrate your apps to use the new key.

Before rotating an API key :

• First try to restrict your API keys as described in Restrict your API keys .

• If restricting your API key is not possible due to conflicting application restriction types, migrate to multiple new (restricted) keys as described in Migrate to multiple API keys . Migrating lets you control the migration and roll out timeline to the new API keys.

If the preceding suggestions aren't possible , and you must rotate your API key to prevent unauthorized use, then follow these steps:

1. Open the Google Cloud console Google Maps Platform Credentials page.

2. Open the API key you want to rotate.

3. At the top of the page, select Rotate key .

4. Optionally, change the API key name.

5. Select Create .

6. Update your applications to use the new key.

After you have updated your applications to using the new key, delete the old key by clicking the Delete the previous key button under the Previous Key section of the new API key page.

Migrate to multiple API keys

To migrate from using one API key for multiple apps to a single unique API key for each app, do the following:

1. Identify which apps need new keys :

   • Web apps are the easiest to update, since you control all of the code. Plan to update all of your web-based apps' keys.
   • Mobile apps are much harder, since your customers must update their apps before the new keys can be used.

2. Create and restrict the new keys : Add both an application restriction and at least one API restriction. For more information, see Recommended best practices .

3. Add the new keys to your apps : For mobile apps, this process may take months until all of your users update to the latest app with the new API key.

Split client-side and server-side usage into separate projects

If you need to call Google Maps Platform services both from server-side applications and directly from client-side applications running end-user devices, Google recommends splitting up your usage between two separate projects.

This approach lets you apply appropriate per-minute, per-user quota limits on most Google Maps Platform services on your client-side project, helping to make sure all end users get their fair share of your overall project quota without impacting each other.

However, since per-user quota restrictions impact both client-side and server-side applications, if you also require high bandwidth for your server-side jobs, set up a separate project for this use case, configured with a higher per-user quota limit, or no limit at all.

Disable unused services

Don't leave unused services enabled on a project, as this practice is vulnerable to abuse, especially if you have not restricted all your public API keys. As a best practice, only enable a service on a project once it is needed by your applications.

Adding API restrictions on a key prevent its use on services that it hasn't been authorized for, but API restrictions only apply to that specific key. Disable a service at the project level to prevents unauthorized use of the service on any key linked to the project.

Use client-side SDKs

When using provided client-side Google Maps Platform SDKs, you will always be able to apply proper restrictions to your API key to secure your service usage.

Using client-side SDKs will also allow you to adopt more advanced security mechanism, such as Firebase App Check on the Maps Platform API surfaces that support it. See Use App Check to secure your API key for further details.

If client-side SDKs are not available for your platform, see Secure your client-side web service calls .

For the availability of client-side Google Maps Platform SDKs for different platforms, see Recommended application and API restrictions .

Protect Static Web API usage

Static Web APIs, such as the Maps Static API and Street View Static API, are similar to web service API calls.

You call both using an HTTPS REST API, and you typically generate the API request URL on the server. However, instead of returning a JSON response, Static Web APIs generate an image that you can embed in generated HTML code. More importantly, it is generally the end-user client , not the server, that calls the Google Maps Platform service.

Use a digital signature

As a best practice, always use digital signatures in addition to an API key. Also, review how many unsigned requests you want to allow per day and adjust your unsigned request quotas accordingly.

For more details about digital signatures, see the Digital Signature Guide .

Protect your signing secret

To protect Static Web APIs, don't embed your API signing secrets directly in code or in the source tree, or expose them in client-side applications. Follow these best practices for protecting your signing secrets:

• Generate your signed Maps Static API and Street View Static API request URLs server-side when serving a web page, or in response to a request from your mobile application .

  For static web content, you can use the Sign a URL now widget on the Cloud Console Google Maps Platform Credentials page.

  For dynamic web content, see the available URL request signing code samples .

• Store signing secrets outside of your application's source code and source tree . If you put your signing secrets or any other private information in environment variables or include files that are stored separately and then share your code, then signing secrets are not included in the shared files. If you store signing secrets or any other private information in files, keep the files outside your application's source tree to keep your signing secrets out of your source code control system. This precaution is particularly important if you use a public source code management system, such as GitHub.

Protect web service API keys

For secure use of Google Maps Platform APIs and services from client-side apps, see Use client-side SDKs and Secure client-side web service calls .

Store API keys outside of your application's source code or source tree . If you put your API keys or any other information in environment variables or include files that are stored separately and then share your code, the API keys are not included in the shared files. This is particularly important if you use a public source code management system, such as GitHub.

To help shield your web service API key against accidental use, Google recommends applying API restrictions to any key used for Maps Platform. Furthermore, also applying IP address restrictions to your web service key will protect it against help protect it against unauthorized use from other source IP addresses, even if the key accidentally leaks.

Use OAuth for server-side apps

OAuth 2.0 is an open standard for access delegation.

While the OAuth 2.0 protocol supports use cases, where an end user authorizes an application to access personal data on their behalf, the intended use case for OAuth 2.0 with Maps Platform is for the developer to utilize temporary access tokens for authorizing their application to call an API on behalf of their Google Cloud project service account with the permissions of the service account.

As a service account may have extremely broad permissions, OAuth 2.0 is recommended for authorizing server-to-server calls between a developer's trusted server-side applications and Google's Maps Platform servers.

For client-side applications running on end user devices, other authentication methods, such as API keys, are recommended.

If you want to use OAuth 2.0 to authorize server-to-server traffic, look for the OAuth topic in your API documentation.

For example, here is the OAuth topic for the Address Validation API .

Secure client-side web service calls

If client-side SDKs are not available, see the recommendations below.

از یک سرور پروکسی استفاده کنید

Using a secure proxy server provides a solid source for interacting with a Google Maps Platform web service endpoint from a client-side application without exposing your API key, signing secret or Google Cloud service account to unauthorized users.

نکات کلیدی:

• Construct your Google Maps Platform requests on the proxy server. Don't allow clients to relay arbitrary API calls using the proxy.

• Post-process the Google Maps Platform responses on your proxy server. Filter out data that the client doesn't need.

For more information about using a proxy server, see Living Vicariously: Using Proxy Servers with the Google Data API Client Libraries .

Secure direct mobile web service calls

If you are unable to set up a secure proxy server for your client-side app, secure your application using the following steps:

1. Use HTTP headers:

   • Android : Use the X-Android-Package and X-Android-Cert HTTP headers.

   • iOS : Use the X-Ios-Bundle-Identifier HTTP header.

2. Add the corresponding application restrictions to your Android or iOS key.

3. Before you consider issuing calls directly from your mobile application to a Google Maps Platform REST API web service, verify that requests with incorrect Android or iOS application identifiers are rejected.

   If Android and iOS application restrictions are not supported on the tested endpoint, Google strongly recommends that you use a secure proxy server between your mobile clients and the Google Maps Platform web service endpoint.

Tips for Android applications:

• Before you integrate your Android application with Google Maps Platform services, verify that your application ID (also called package name) is formatted correctly. For details, see Configure app module . in the Android documentation.

• To pass X-Android-Package directly from your application, look it up programmatically using Context.getPackageName() .

• To pass X-Android-Cert directly from your applications, calculate the required SHA-1 fingerprint of your application signing certificates, accessible through PackageInfo.signingInfo .

• If you authorize your Android application using the Google Cloud console, note that the UI expects the SHA-1 fingerprint to be a colon-delimited string, eg, 00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33 . However, the gcloud tool and the API keys API expect the hexadecimal string without delimiters.

Tips for iOS applications:

• Before you integrate your iOS application with Google Maps Platform services, verify that your Bundle ID is formatted correctly .

• You should typically always pass the Bundle ID of your main bundle in the X-Ios-Bundle-Identifier header, when authorizing your iOS application.

For further information, refer to articles Manage API keys and Use API keys to access APIs .

Host your browser based apps on a server

Frameworks, such as Apache Cordova, allow you to conveniently create multi-platform hybrid apps running inside a webview. However, API key website restrictions are not guaranteed to work correctly, unless your web app is loaded using HTTP or HTTPS from a website that you control and have authorized.

Bundled resources, loaded locally from within a hybrid application, or accessed using a local file URL will in many cases prevent referrer based authorization from working as the browser engine powering your webview will omit sending the Referer header. To avoid this, host your web applications server-side, not client-side.

Alternatively, for mobile applications, consider using available native Google Maps Platform Android and iOS SDKs, instead of using a web based SDK.

برای ایمن‌سازی کلید API خود از App Check استفاده کنید

Certain Maps SDKs and APIs allow you to integrate with Firebase App Check . App Check provides protection for calls from your app to Google Maps Platform by blocking traffic that comes from sources other than legitimate apps. It does this by checking for a token from an attestation provider. Integrating your apps with App Check helps to protect against malicious requests, so you're not charged for unauthorized API calls.

App Check integration instructions:

• SDK مکان‌ها برای iOS
• SDK مکان‌ها برای اندروید
• API جاوا اسکریپت نقشه‌ها
• Place class, Maps JavaScript API

Handle unauthorized use of an API key

If you detect use of your API key that is unauthorized, do the following to address the problem:

1. Restrict your keys : If you've used the same key in multiple apps, migrate to multiple API keys, and use separate API keys for each app. For more details, see:

   • Restrict your API keys
   • Migrate to multiple API keys
   • Use separate API keys for each app

2. If you use the Places SDK or the Maps Javascript API, you can also use App Check to secure your API Key .

3. Only replace or rotate keys if the following is true:

   • You detect unauthorized usage on keys that either cannot be restricted or are already restricted, and App Check is not applicable.

   • You want to move more quickly to secure your API key and stop the abuse, even if it might impact legitimate traffic from your application.

   Before proceeding, read through Be careful when rotating API keys .

4. If you are still having issues or need help, contact support .

Recommended application and API restrictions

The following sections suggest appropriate application and API restrictions for each Google Maps Platform API, SDK or service.

Recommended API Restrictions

The following guidelines for API restrictions apply to all Google Maps Platform services:

• Restrict your API key to only the APIs you are using it for, with the following exceptions:

  • If your app uses the Places SDK for Android or Places SDK for iOS, authorize Places API (New) or Places API, depending on the SDK versions you use. ¹

  • If your app uses Maps JavaScript API, always authorize it on your key.

  • If you also use any of the following Maps JavaScript API services, you should also authorize these corresponding APIs:

    خدمات	API restriction
    Directions Service (Legacy)	Directions API (Legacy)
    Distance Matrix Service (Legacy)	Distance Matrix API (Legacy)
    خدمات ارتفاع	API ارتفاع
    سرویس ژئوکدینگ	API کدگذاری جغرافیایی
    Place class, Place Autocomplete Widget (New) & Place Autocomplete Data API	Places API (New) 2
    Places Library, Places Service & Place Autocomplete Widget	Places API 2

¹ For more details, see the Places SDK for Android and Places SDK for iOS documentation.

² If you are unsure if you need to authorize Places API (New) or Places API, see the Maps JavaScript API documentation.

چند مثال:

• You are using the Maps SDK for Android and Places SDK for Android, so you include the Maps SDK for Android and Places API (New) as API restrictions.

• Your website uses the Maps JavaScript API Elevation Service and the Maps Static API, so you add API restrictions for all of the following APIs:

  • API جاوا اسکریپت نقشه‌ها
  • API ارتفاع
  • API استاتیک نقشه‌ها

Recommended application Restriction

وب‌سایت‌ها

For websites using Maps JavaScript API services, Maps Static API or Street View Static API or calling recent Google Maps Platform services directly over the HTTPS REST API or gRPC, use the Websites application restriction:

Directions Service (Legacy) Distance Matrix Service (Legacy) خدمات ارتفاع سرویس ژئوکدینگ

Maps JavaScript API 1 Places Library 2 Maps Static API 3 Street View Static API 3

¹ For mobile applications, consider using the native Maps SDK for Android and Maps SDK for iOS .

² For mobile applications, consider using the native Places SDK for Android and Places SDK for iOS .

³ See also Protect Static Web API usage .

Websites with the Maps Embed API

While using the Maps Embed API is no charge, you should still restrict any used API key to prevent abuse on other services.

Best practice : Create a separate API key for Maps Embed API use, and restrict this key to only the Maps Embed API. This restriction sufficiently secures the key, preventing its unauthorized use on any other Google service. For full control over where your Maps Embed API key can be used from, Google recommends also applying Websites application restrictions.

If you are unable to separate your Maps Embed API usage to a separate API key, secure your existing key using the Websites application restriction.

Apps and servers using web services

For servers and client-side apps from trusted corporate internal networks using web services together with API keys, use the IP addresses application restriction.

Use for apps and servers using these APIs:

API اعتبارسنجی آدرس API نمای هوایی کیفیت هوا (Air Quality API) Directions API (Legacy) 4 Distance Matrix API (Legacy) 4 API ارتفاع Geocoding API 5 Geolocation API 6 API کاشی‌های نقشه

API مجموعه داده‌های نقشه‌ها Places API (New) 7 Places API 6 API جاده‌ها Routes API 4 Pollen API API خورشیدی Time Zone API 8 رابط برنامه‌نویسی کاربردی آب و هوا

⁴ For mobile applications, consider using the Navigation SDK.

⁵ For safe mobile usage, use a secure proxy server .

⁶ For client-side applications, consider using the native geolocation service offered by the platform; for example, W3C Geolocation for web browsers, LocationManager or the Fused Location Provider API for Android, or the Apple Core Location framework for iOS.

⁷ For mobile applications, consider using the native Places SDK for Android and Places SDK for iOS .

⁸ For safe client-side usage, use a secure proxy server .

برنامه‌های اندروید

For apps on Android, use the Android apps application restriction. Use for apps using these SDKs:

• SDK نقشه‌ها برای اندروید
• SDK مکان‌ها برای اندروید
• SDK ناوبری برای اندروید

In addition, prevent accidentally checking API keys into version control by using the Secrets Gradle Plugin to inject secrets from a local file rather than storing them in the Android Manifest.

اپلیکیشن‌های iOS

For apps on iOS, use the iOS apps application restriction. Use for apps and servers using these SDKs:

• SDK نقشه برای iOS
• SDK مکان‌ها برای iOS
• کیت توسعه نرم‌افزار ناوبری برای iOS

مطالعه بیشتر

• مدیریت کلیدهای API
• Use API keys to access APIs
• Optimize your Google Maps Platform usage with quotas (video)
• How to generate and restrict API keys for the Google Maps Platform (video)
• Restricting API keys
• Securing API keys when using Static Maps and Street View APIs
• 15 Google Maps platform Best Practices