رسائل الخطأ في Maps Static API

تعرض واجهة Maps Static API رسالة خطأ أو تحذير عند تعذُّر تنفيذ طلب. يوضّح هذا الدليل رسائل الخطأ ويقدّم تعليمات حول كيفية حلّها.

الطلبات غير الصالحة

في حال تقديم طلب غير صالح، تعرض Maps Static API رمز الحالة 4xx HTTP ورسالة تصف المشكلة، كما هو موضّح في القائمة التالية. يمكنك الاطّلاع على رمز الخطأ الفعلي والرسالة التي تعرضها واجهة برمجة التطبيقات للحصول على تفاصيل حول المشاكل المحدّدة.

يتضمّن الطلب مَعلمة غير صالحة أو مَعلمة مطلوبة غير متوفّرة. على سبيل المثال، لا تقع المَعلمة size ضمن النطاق المتوقّع للقيم الرقمية، أو أنّها غير متوفّرة في الطلب.
400 BAD REQUEST
مفتاح واجهة برمجة التطبيقات المضمّن في الطلب غير صالح.
403 FORBIDDEN

الأخطاء التي تمنع عرض الخريطة

إذا كان الطلب صالحًا، ولكن حدث خطأ آخر يمنع عرض الخريطة، ستعرض Maps Static API نصًا أو صورة خطأ بدلاً من الخريطة. على سبيل المثال، يحدث خطأ عندما يتجاوز التطبيق حدود الاستخدام.

عرض صورة خطأ بدلاً من خريطة
يتم عرض صورة خطأ بدلاً من الخريطة

إذا كنت تستخدم Maps Static API بدون مفتاح API، أو إذا لم يتم تفعيل الفوترة في حسابك، ستعرض الصفحة صورة خطأ بدلاً من الخريطة، مع رابط يشير إلى نوع الخطأ. على سبيل المثال، "g.co/staticmaperror/key".

الأخطاء والحلول بدون مفتاح
خطأ متعلق بسقوف الاستخدام: تم تجاوز الحدّ الأقصى المسموح به لعمليات تحميل الخرائط اليومية أنت تستخدم Maps Static API بدون مفتاح واجهة برمجة تطبيقات. لحلّ هذا الخطأ، أكمِل الخطوات التالية:
  1. الحصول على مفتاح واجهة برمجة التطبيقات
  2. تفعيل الفوترة
  3. توقيع عنوان URL
خطأ متعلق بسقوف الاستخدام: عناوين URL للطلبات لا تتضمّن التوقيع الرقمي لا يتضمّن طلبك توقيعًا رقميًا مطلوبًا. لحلّ هذا الخطأ، وقِّع عنوان URL.

تتضمّن تحذيرات

في بعض حالات الخطأ، تعرض واجهة برمجة التطبيقات خريطة، ولكن قد لا تتضمّن الخريطة بعض المعلومات. عند حدوث ذلك، يمكنك تحديد التحذير باستخدام الشروط التالية:

  • تظهر الخريطة مع شريط أصفر للخطأ فوقها، ويحتوي الشريط على النص "خطأ في الخريطة: g.co/staticmaperror".
  • تعرض واجهة برمجة التطبيقات تحذيرًا في شكل عنوان HTTP باسم X-Staticmap-API-Warning.

على سبيل المثال، يحتوي عنوان URL التالي على قيمة غير متوقّعة في المَعلمة markers:

https://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&scale=1&size=400x400&markers=sdgaags&key=YOUR_API_KEY

تعرض واجهة برمجة التطبيقات خريطة، ولكن يظهر شريط أصفر للخطأ فوق الصورة مع النص "خطأ في الخريطة: g.co/staticmaperror":

تظهر الخريطة مع الخطأ: g.co/staticmaperror
خريطة تعرض شريط تحذير باللون الأصفر

تعرض واجهة برمجة التطبيقات أيضًا عنوان HTTP التالي:

X-Staticmap-API-Warning:Error geocoding: marker 1

يوضّح الجدول التالي التحذيرات التي يمكن أن تصدرها واجهة برمجة التطبيقات كعناوين HTTP:

تحذيرات في عناوين X-Staticmap-API-Warning
Error geocoding: [center, ][marker #number, ][visible #num, ][path #num, ]* حدث خطأ أثناء محاولة ترميز الطلب جغرافيًا. تتوفّر صيغ مختلفة لهذه الرسالة، وذلك حسب العنصر الذي تعذّر فيه الترميز الجغرافي، مثل center أو marker أو visible أو path، وعدد العناصر التي تعذّر ترميزها. أحد الأمثلة على هذا التحذير هو X-Staticmap-API-Warning:Error geocoding: marker 1، كما هو موضّح في المثال السابق.
Too many geocoded markers requested (max is 15). يحدّد الطلب عددًا من العلامات يتجاوز الحد الأقصى المسموح به مع عنوان يمكن قراءته. الحد الأقصى هو 15. لا ينطبق هذا الحدّ إلا على العلامات المحدّدة كعنوان يمكن قراءته ويتطلّب ترميزًا جغرافيًا. ولا ينطبق ذلك على العلامات المحدّدة باستخدام إحداثيات خطوط الطول والعرض.
Too many geocoded polyline vertices requested (max is 15). يحدّد الطلب عددًا من الخطوط المتعددة أكبر من الحد الأقصى المسموح به مع عنوان يمكن قراءته. الحد الأقصى هو 15. لا ينطبق هذا الحدّ إلا على الخطوط المتعددة الأضلاع التي تم تحديد رؤوسها كعناوين يمكن قراءتها، والتي تتطلّب ترميزًا جغرافيًا. ولا ينطبق على الخطوط المتعددة الأضلاع المحدّدة بإحداثيات خطوط العرض والطول.

يمكنك الاطّلاع على تحذيرات عناوين HTTP في وحدة تحكّم أدوات مطوّري البرامج في Chrome أو وحدة تحكّم الويب في Firefox أو أدوات أخرى مماثلة في المتصفّح.