التوافق البديل

لست مضطرًا إلى تعلم هذا API لاستخدامه. لسبعة عشر API آخر للترميز الجغرافي والاستعلام عن IP نشغّل مضيفًا يقبل صيغة طلب ذلك المزوّد ويجيب بصيغة استجابته، وخلفه بياناتنا. وينطبق الأمر نفسه على مكتبات خرائط JavaScript التي يوفرها هؤلاء المزوّدون. الانتقال مجرد تغيير لاسم المضيف.

كيف يعمل

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

غيّر المضيف. يصبح maps.googleapis.com هو gapi.mygeocode.com، ويصبح dev.virtualearth.net هو bing.mygeocode.com، وهكذا. يضم الجدول أدناه كل الأزواج.
استبدل المفتاح، أو استغنِ عنه. ضع مفتاح My Geocode في المعامل الذي كان يستخدمه المفتاح القديم (key أو apiKey أو access_token أو token...). يحصل أي عنوان على 2,500 طلب مجاني يوميًا دون مفتاح، ويأتي كل مفتاح مع 2,500 طلب خاصة به، لذا لا يكلّف الانتقال والاختبار شيئًا.
قارن. شغّل عينة من الطلبات الحقيقية على كلا المضيفين. ستختلف الإحداثيات قليلًا لأن البيانات مختلفة، أما أسماء الحقول فلن تختلف.

قبل

$ curl "https://maps.googleapis.com/maps/api/geocode/json?address=10+Downing+St+London&key=GOOGLE_KEY"

بعد

$ curl "https://gapi.mygeocode.com/maps/api/geocode/json?address=10+Downing+St+London&key=MYGEOCODE_KEY"

جميع المضيفات البديلة المتوافقة

يعمل كل مضيف على البنية التحتية نفسها والبيانات نفسها والحصة المجانية نفسها والأسعار نفسها التي يعمل بها api.mygeocode.com. انقر على مزوّد لعرض قائمة نقاط النهاية الخاصة به ونموذج استجابة والاختلافات المعروفة.

المزوّد وعمليات الاستعلام	المضيف الأصلي	المضيف البديل المتوافق	معامل المفتاح
Google Maps Platform أمامي، عكسي، إكمال تلقائي، منطقة زمنية، ارتفاع	`maps.googleapis.com`	`gapi.mygeocode.com`	`key`
Bing Maps REST Services أمامي، عكسي، إكمال تلقائي، منطقة زمنية، ارتفاع	`dev.virtualearth.net`	`bing.mygeocode.com`	`key`
HERE Geocoding and Search أمامي، عكسي، إكمال تلقائي	`geocode.search.hereapi.com` `revgeocode.search.hereapi.com` `autosuggest.search.hereapi.com` `autocomplete.search.hereapi.com`	`here.mygeocode.com`	`apiKey`
Mapbox Geocoding أمامي، عكسي، إكمال تلقائي	`api.mapbox.com`	`mapbox.mygeocode.com`	`access_token`
Geocode.Farm أمامي، عكسي	`api.geocode.farm` `www.geocode.farm`	`farm.mygeocode.com`	`key`
OpenStreetMap Nominatim أمامي، عكسي	`nominatim.openstreetmap.org`	`osm.mygeocode.com`	لا يوجد، أضف `key` أو الترويسة
OpenCage أمامي، عكسي	`api.opencagedata.com`	`opencage.mygeocode.com`	`key`
LocationIQ أمامي، عكسي، إكمال تلقائي، منطقة زمنية	`us1.locationiq.com` `eu1.locationiq.com`	`locationiq.mygeocode.com`	`key`
Geoapify أمامي، عكسي، إكمال تلقائي، استعلام عن IP	`api.geoapify.com`	`geoapify.mygeocode.com`	`apiKey`
TomTom Search أمامي، عكسي، إكمال تلقائي	`api.tomtom.com`	`tomtom.mygeocode.com`	`key`
MapQuest Geocoding أمامي، عكسي	`www.mapquestapi.com` `open.mapquestapi.com`	`mapquest.mygeocode.com`	`key`
Geocodio أمامي، عكسي	`api.geocod.io`	`geocodio.mygeocode.com`	`api_key`
PositionStack أمامي، عكسي	`api.positionstack.com`	`positionstack.mygeocode.com`	`access_key`
ip-api.com استعلام عن IP	`ip-api.com` `pro.ip-api.com`	`ipapi.mygeocode.com`	`key`
ipinfo.io استعلام عن IP	`ipinfo.io`	`ipinfo.mygeocode.com`	`token`
ipstack استعلام عن IP	`api.ipstack.com`	`ipstack.mygeocode.com`	`access_key`
Open-Elevation Elevation	`api.open-elevation.com`	`openelevation.mygeocode.com`	لا يوجد، أضف `key` أو الترويسة

مكتبات خرائط JavaScript

تكون آلام تغيير المزوّد أشد في المتصفح، حيث تتشابك الخريطة وأداة الترميز الجغرافي والفوترة معًا. بالنسبة إلى المكتبات أدناه، تُحمَّل المكتبة نفسها من مضيفنا (أو، في حالة MapLibre وMapbox GL وLeaflet، تُوجَّه إلى مضيفنا عبر الإعدادات) وتحتفظ بواجهتها البرمجية العامة: google.maps.Map وMicrosoft.Maps.Map وH.Map وسائرها. تأتي البلاطات والترميز الجغرافي والإكمال التلقائي والارتفاع منا. تحميل الخرائط والبلاطات مجاني، أما استدعاءات الترميز الجغرافي فتُحتسب كالمعتاد.

المكتبة	تُحمَّل من	حمّلها بدلًا من ذلك من	ما يستمر في العمل
واجهة Google Maps JavaScript API	`maps.googleapis.com`	`gapi.mygeocode.com`	google.maps.Map مع بلاطاتنا (أنواع الخرائط roadmap وsatellite وterrain)
عنصر التحكم Bing Maps V8 Web Control	`www.bing.com`	`bing.mygeocode.com`	الفئات Microsoft.Maps.Map وLocation وLocationRect وPushpin وInfobox وPolyline وPolygon وLayer
Mapbox GL JS وmapbox-gl-geocoder		`mapbox.mygeocode.com`	أنماط البلاطات المتجهية: streets وlight وdark وoutdoors، وفق مواصفات أنماط Mapbox
إضافات الترميز الجغرافي في Leaflet	`tile.openstreetmap.org`	`tiles.mygeocode.com`	Leaflet Control Geocoder: أدوات الترميز الجغرافي nominatim وgoogle وbing وmapbox وhere وopencage وlatLng وmapquest، كل منها موجّه إلى مضيف www.mygeocode.com المقابل
واجهة HERE Maps API for JavaScript	`js.api.here.com`	`here.mygeocode.com`	H.Map, H.map.Marker, H.map.Polyline, H.map.Polygon, H.map.Group
MapQuest.js	`api.mqcdn.com`	`mapquest.mygeocode.com`	L.mapquest.map وtileLayer (map وhybrid وsatellite وlight وdark)

تحتوي صفحة بدائل JavaScript المتوافقة على مقتطفات الكود قبل التغيير وبعده، وقائمة بما هو مضمّن وما هو غير مضمّن لكل مكتبة، وعناوين URL للبلاطات والأنماط.

أين يوضع المفتاح

يقبل كل مضيف المفتاح في المكان الذي يتوقعه المزوّد الأصلي، وكذلك في الترويسة X-API-Key. المفتاح اختياري: 2,500 طلب يوميًا لكل عنوان لا تحتاج إلى مفتاح. يستغرق الحصول على مفتاح مجاني دقيقة، ويضيف الرصيد والباقات وسجل الاستخدام. يمكن استخدام مفتاح الدفع حسب الاستخدام من عنوانَي IP في كل 24 ساعة متجددة ومفتاح Unlimited من ثلاثة، فاستخدم مزيدًا من المفاتيح أو الباقات لمزيد من العناوين (راجع المصادقة).

المعامل	يستخدمه
`key`	Google Maps وBing Maps وGeocode.Farm وOpenCage وLocationIQ وTomTom وMapQuest وip-api (pro)
`apiKey`	HERE وGeoapify
`access_token`	Mapbox
`api_key`	Geocodio
`access_key`	PositionStack وipstack
`token` أو `Authorization: Bearer`	ipinfo وHERE
لا يوجد	Nominatim وOpen-Elevation. أضف `key=...` إلى الاستعلام أو أرسل الترويسة `X-API-Key`.

الحصة والأخطاء على المضيفات البديلة المتوافقة

الحصة اليومية هي نفسها في كل مكان آخر، وتُحتسب لكل مفتاح، أو لكل عنوان إذا لم يُرسل مفتاح، عبر api.mygeocode.com وكل مضيف بديل متوافق: 2,500 طلب مجاني يوميًا، ثم الرصيد أو مفتاح Unlimited. تُرسل الترويسات X-Quota-* وX-Key-IPs-* على كل مضيف، لذا يمكنك قراءة الحالة الحقيقية من الترويسات أيًا كانت صيغة جسم الاستجابة. أما في جسم الاستجابة فيُبلّغ عن الحدود بالطريقة التي يبلّغ بها المزوّد:

المضيف	نفاد الرصيد (402)	مفتاح خاطئ أو مفقود أو مقيّد بعناوين IP	طلب غير صالح
gapi.mygeocode.com	HTTP 200، `"status": "OVER_QUERY_LIMIT"`	`"status": "REQUEST_DENIED"`	`"status": "INVALID_REQUEST"`
bing.mygeocode.com	`"statusCode": 429` في الغلاف	`"statusCode": 401`, `authenticationResultCode: InvalidCredentials`	`"statusCode": 400` مع `errorDetails`
here.mygeocode.com	HTTP 429، `{"title": "Too Many Requests", "status": 429}`	HTTP 401 مع `error_description`	HTTP 400 مع `title` و`cause`
mapbox.mygeocode.com	HTTP 429، `{"message": "Rate limit exceeded"}`	HTTP 401، `{"message": "Not Authorized - Invalid Token"}`	HTTP 422 مع `message`
osm.mygeocode.com	HTTP 429، `{"error": {"code": 429, "message": "..."}}`	لا ينطبق	HTTP 400، `{"error": {"code": 400, "message": "..."}}`
ipapi.mygeocode.com	HTTP 200، `{"status": "fail", "message": "quota"}`	`{"status": "fail", "message": "invalid key"}`	`{"status": "fail", "message": "invalid query"}`
الآخرون	كما هو موثّق لدى المزوّد، راجع صفحة كل مضيف

ما يتطابق وما لا يتطابق

متطابق

المسارات والطرق ومعاملات الاستعلام التي يوثّقها المزوّد.
بنية الاستجابة: أسماء الحقول، والتداخل، والمصفوفات، والأنواع، وترتيب الإحداثيات (بما في ذلك ترتيب Mapbox [lon, lat]).
مفردات الحالة والثقة (ROOFTOP وHigh وhouseNumber وEXACT_MATCH...)، مربوطة من قيمتي precision وconfidence لدينا.
أشكال الأخطاء، حتى تستمر المعالجة الحالية في العمل.
الأسعار والحصة: لا تكلفة إضافية لاستخدام مضيف بديل متوافق.

المختلف

البيانات. الإحداثيات والسلاسل المنسّقة وقيم الثقة هي بياناتنا ولن تطابق الأصل رقمًا برقم. تختلف التغطية على مستوى المنزل من دولة إلى أخرى، راجع التغطية.
المعرّفات. معرّفات الأماكن خاصة بنا وثابتة، لكن لا يمكن إرسالها إلى المزوّد الأصلي.
أي شيء خارج الترميز الجغرافي والإكمال التلقائي وIP والمنطقة الزمنية والارتفاع: التوجيه، وتفاصيل الأماكن، والصور، وحركة المرور، وStreet View. تسرد صفحة كل مضيف ما هو غير متوفر.
المفاتيح: عنوانا IP في كل 24 ساعة متجددة لمفتاح الدفع حسب الاستخدام، وثلاثة لمفتاح Unlimited، كما في نقاط النهاية الخاصة بنا.

قائمة التحقق للانتقال

ابحث في الكود والإعدادات عن اسم مضيف المزوّد. كثيرًا ما يكون في أكثر من مكان: كود الخادم، وتطبيقات الجوال، وقاعدة في CDN، وإعدادات مخزّنة مؤقتًا.
غيّره إلى المضيف البديل المتوافق من الجدول أعلاه. احتفظ بالمسار.
استبدل المفتاح بمفتاح My Geocode. استخدم مفتاحًا واحدًا لكل خادم أو مفتاحين على الأكثر، فمفتاح الدفع حسب الاستخدام يقبل عنوانَي IP في كل 24 ساعة متجددة، ومفتاح Unlimited ثلاثة.
شغّل مجموعة الاختبارات الحالية لديك. ينبغي أن تنجح دون تغيير. إذا غاب حقل تعتمد عليه، فراجع صفحة المضيف لمعرفة الثغرات المعروفة وأخبرنا.
أعد تشغيل بضع مئات من الطلبات الحقيقية على كلا المضيفين وقارن الإحداثيات والحقول التي تعرضها. انظر إلى precision حيث يكشفها المضيف البديل (باسم location_type أو accuracy أو resultType وما إلى ذلك).
راقب X-Quota-Used ليوم واحد لتحديد حجم خطتك: الرصيد لأقل من نحو 19,000 طلب يوميًا، ومفتاح Unlimited لما فوق ذلك.
ألغِ الفوترة القديمة.

حزم SDK الخاصة بالمزوّدين

تقبل معظم مكتبات العملاء الرسمية عنوان URL أساسيًا مخصصًا، لذا تعمل مع المضيفات البديلة المتوافقة أيضًا: عملاء Google Maps Services (googlemaps بلغة Python و@googlemaps/google-maps-services-js)، وحزم Mapbox SDK (الخيار origin)، وعملاء REST من HERE، ومكتبات ipinfo، وأغلفة Nominatim مثل geopy (domain=). وجّهها إلى المضيف الوارد في الجدول ومرّر مفتاح My Geocode حيث كان مفتاح المزوّد.

مزوّد غير مدرج

إضافة مضيف تستغرق بضعة أيام من العمل عندما تكون صيغة المزوّد موثّقة. إذا كنت تستخدم خدمة غير موجودة هنا، فأخبرنا بها وبعدد الطلبات التي ترسلها يوميًا تقريبًا. كانت الإضافات الأخيرة كلها بناءً على طلبات المستخدمين.