رسائل الخطأ في واجهة برمجة التطبيقات الثابتة للخرائط

قد تُصدر واجهة Maps Static API خطأً أو تحذيرًا عند حدوث خطأ. يشرح هذا الدليل كل رسالة خطأ، ويقدّم المزيد من التعليمات لحل الأخطاء.

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

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

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

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

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

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

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

الأخطاء والحلول بدون مفتاح
خطأ في حدود الاستخدام: تم تجاوز الحد الأقصى المقدم لتحميل الخرائط اليومية استخدام واجهة برمجة التطبيقات الثابتة للخرائط بدون مفتاح واجهة برمجة التطبيقات. لحلّ المشكلة، يجب إجراء ما يلي:
  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, ]* حدث خطأ أثناء محاولة ترميز الطلب جغرافيًا. هناك عدة صيغ لهذه الرسالة استنادًا إلى العنصر الذي تعذّر ترميزه جغرافيًا (مثل المركز أو العلامة أو العنصر المرئي أو المسار) وعدد العناصر التي تعذّر ترميزها. وأحد الأمثلة على هذا التحذير هو 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 أو أي أدوات أخرى مكافئة في متصفّحك.