طلب ترميز الموقع الجغرافي والرد عليه

الطلب

يتخذ طلب واجهة برمجة التطبيقات للترميز الجغرافي الصيغة التالية:

https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters

حيث يمكن أن تكون السمة outputFormat إحدى القيمتَين التاليتَين:

  • تشير السمة json (ننصح بها) إلى الإخراج في JavaScript Object Notation (JSON).
  • تشير السمة xml إلى الإخراج بتنسيق XML.

يجب استخدام HTTPS للطلبات التي تستخدم مفتاح واجهة برمجة التطبيقات.

تكون بعض المعلمات مطلوبة بينما يكون البعض الآخر اختياريًا. وكما هو الحال في عناوين URL، يتم فصل المَعلمات باستخدام حرف العطف (&).

في الجزء المتبقي من هذه الصفحة، يتم وصف الترميز الجغرافي والترميز الجغرافي العكسي بشكل منفصل، وذلك بسبب توفُّر معلَمات مختلفة لكل نوع من الطلبات.

معلمات الترميز الجغرافي (البحث عن خطوط الطول/العرض)

المَعلمات المطلوبة في طلب الترميز الجغرافي:

  • address — عنوان الشارع أو رمز الجمع الذي تريد ترميزه جغرافيًا. حدد العناوين وفقًا للتنسيق الذي تستخدمه الخدمة البريدية الوطنية للبلد المعني. ويجب تجنُّب عناصر العنوان الإضافية، مثل أسماء الأنشطة التجارية وأرقام الوحدات أو الأجنحة أو الطوابق. يجب الفصل بين عناصر عنوان الشارع بمسافات (كما هو موضح هنا على شكل أحرف إلغاء عنوان URL إلى %20): 
    address=24%20Sussex%20Drive%20Ottawa%20ON
    يجب تنسيق رموز الجمع كما هو موضّح هنا (يتم تخطي علامات عناوين URL باستخدام أحرف الإلغاء في %2B ويتم استبدال عناوين URL بحروف الإلغاء إلى %20):
    • الرمز العام هو رمز منطقة مكوّن من 4 أحرف و6 أحرف أو أكثر (رمز 849VCWC8+R9 تساوي 849VCWC8%2BR9).
    • الرمز المركَّب هو رمز محلي يتألف من 6 أحرف أو أكثر مع موقع جغرافي صريح (CWC8+R9 Mountain View, CA, USA هو CWC8%2BR9%20Mountain%20View%20CA%20USA).

    --OR--
    components: فلتر مكوّنات يحتوي على عناصر تفصل بينها شرطة مائلة (|). ويتم قبول فلتر المكوّنات أيضًا كمَعلمة اختيارية في حال توفير address. يتكون كل عنصر في فلتر المكونات من زوج component:value، ويحظر النتائج الواردة من أداة الترميز الجغرافي بشكل كامل. يمكنك الاطّلاع على مزيد من المعلومات حول فلترة المكوّنات أدناه.
  • key — مفتاح واجهة برمجة التطبيقات لتطبيقك ويحدِّد هذا المفتاح تطبيقك لأغراض إدارة الحصص. تعرَّف على كيفية الحصول على مفتاح.

يُرجى مراجعة الأسئلة الشائعة للحصول على إرشادات إضافية.

المَعلمات الاختيارية في طلب الترميز الجغرافي:

  • bounds — المربع المحيط بإطار العرض الذي يتم من خلاله الانحياز في النتائج الجغرافية بشكل أكثر بروزًا. ولن تؤثر هذه المعلمة إلا في النتائج الواردة من أداة الترميز الجغرافي، ولن تحظرها بشكل كامل. (لمزيد من المعلومات، يُرجى الاطّلاع على انحياز إطار العرض أدناه).
  • language: اللغة التي يتم عرض النتائج بها
    • راجِع قائمة اللغات المتاحة. غالبًا ما يعدّل محرّك بحث Google اللغات المتاحة، لذا قد لا تكون هذه القائمة شاملة.
    • إذا لم يتم توفير language، يحاول أداة الترميز الجغرافي استخدام اللغة المفضّلة كما هو محدّد في عنوان Accept-Language، أو اللغة الأصلية للنطاق الذي يتم إرسال الطلب منه.
    • يبذل جهاز الترميز الجغرافي قصارى جهده لتوفير عنوان شارع يمكن لكل من المستخدم والسكان المحليين قراءته. ولتحقيق هذا الهدف، يتم عرض عناوين الشوارع باللغة المحلية، ويتم تحويلها صوتيًا إلى نص برمجي يمكن للمستخدم قراءته إذا لزم الأمر، مع مراعاة اللغة المفضّلة. ويتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض جميع عناصر العنوان باللغة نفسها التي يتم اختيارها من المكوّن الأول.
    • إذا لم يكن الاسم متاحًا باللغة المفضلة، يستخدم الترميز الجغرافي أقرب تطابق.
    • تؤثّر اللغة المفضّلة بشكل طفيف في مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها وترتيب عرضها. يفسر أداة الترميز الجغرافي الاختصارات بشكل مختلف استنادًا إلى اللغة، مثل اختصارات أنواع الشوارع أو المرادفات التي قد تكون صالحة بلغة ما وليس بلغة أخرى. على سبيل المثال، utca وtér مرادفان للشارع والمربّع على التوالي باللغة المجرية.
  • region: رمز المنطقة، ويتم تحديده كنطاق من المستوى الأعلى (ccTLD) المكوّن من حرفَين. ولن تؤثر هذه المعلمة إلا في النتائج الواردة من أداة الترميز الجغرافي، ولا تحظرها بشكل كامل. (لمزيد من المعلومات، راجع انحياز المنطقة أدناه). ويمكن أن تؤثر المَعلمة أيضًا في النتائج استنادًا إلى القانون الساري.
  • components: فلتر مكوّنات يحتوي على عناصر مفصولة بالشرطة الرأسية (|). يكون فلتر المكوّنات مطلوبًا إذا لم يتضمّن الطلب address. يتكون كل عنصر في فلتر المكونات من زوج component:value، ويحظر النتائج الواردة من أداة الترميز الجغرافي بشكل كامل. يمكنك الاطّلاع على مزيد من المعلومات حول فلترة المكوّنات أدناه.

الردود

يتم عرض استجابات الترميز الجغرافي بالتنسيق المُشار إليه في علامة output ضمن طلب عنوان URL أو بتنسيق JSON تلقائيًا.

في هذا المثال، تطلب واجهة برمجة التطبيقات Geocoding API الرد json لطلب بحث عن معرّف المكان "ChIJeRpOeF67j4AR9ydy_PIzPuM". هذا المكان رقم التعريف مخصّص للمبنى الموجود في 1600 Amphitheatre Parkway, Mountain View, CA.

يوضح هذا الطلب استخدام علامة JSON output:

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY

يوضح هذا الطلب استخدام علامة output بتنسيق XML:

https://maps.googleapis.com/maps/api/geocode/xml?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY

اختَر علامات التبويب أدناه للاطّلاع على نماذج ردود JSON وXML.

JSON

{
    "results": [
        {
            "address_components": [
                {
                    "long_name": "1600",
                    "short_name": "1600",
                    "types": [
                        "street_number"
                    ]
                },
                {
                    "long_name": "Amphitheatre Parkway",
                    "short_name": "Amphitheatre Pkwy",
                    "types": [
                        "route"
                    ]
                },
                {
                    "long_name": "Mountain View",
                    "short_name": "Mountain View",
                    "types": [
                        "locality",
                        "political"
                    ]
                },
                {
                    "long_name": "Santa Clara County",
                    "short_name": "Santa Clara County",
                    "types": [
                        "administrative_area_level_2",
                        "political"
                    ]
                },
                {
                    "long_name": "California",
                    "short_name": "CA",
                    "types": [
                        "administrative_area_level_1",
                        "political"
                    ]
                },
                {
                    "long_name": "United States",
                    "short_name": "US",
                    "types": [
                        "country",
                        "political"
                    ]
                },
                {
                    "long_name": "94043",
                    "short_name": "94043",
                    "types": [
                        "postal_code"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
            "geometry": {
                "location": {
                    "lat": 37.4224428,
                    "lng": -122.0842467
                },
                "location_type": "ROOFTOP",
                "viewport": {
                    "northeast": {
                        "lat": 37.4239627802915,
                        "lng": -122.0829089197085
                    },
                    "southwest": {
                        "lat": 37.4212648197085,
                        "lng": -122.0856068802915
                    }
                }
            },
            "place_id": "ChIJeRpOeF67j4AR9ydy_PIzPuM",
            "plus_code": {
                "compound_code": "CWC8+X8 Mountain View, CA",
                "global_code": "849VCWC8+X8"
            },
            "types": [
                "street_address"
            ]
        }
    ],
    "status": "OK"
}

تجدر الإشارة إلى أنّ استجابة JSON تحتوي على عنصرَي جذر:

  • يحتوي "status" على بيانات وصفية في الطلب. يمكنك الاطّلاع على رموز الحالة أدناه.
  • يحتوي "results" على مصفوفة من معلومات العناوين المرمزة جغرافيًا والمعلومات الهندسية.

وبشكل عام، يتم عرض إدخال واحد فقط في صفيف "results" لعمليات البحث عن العنوان، علمًا أنّ الرمز الجغرافي قد يعرض عدة نتائج عندما تكون طلبات البحث عن العنوان غامضة.

XML

<GeocodeResponse>
    <status>OK</status>
    <result>
        <type>street_address</type>
        <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address>
        <address_component>
            <long_name>1600</long_name>
            <short_name>1600</short_name>
            <type>street_number</type>
        </address_component>
        <address_component>
            <long_name>Amphitheatre Parkway</long_name>
            <short_name>Amphitheatre Pkwy</short_name>
            <type>route</type>
        </address_component>
        <address_component>
            <long_name>Mountain View</long_name>
            <short_name>Mountain View</short_name>
            <type>locality</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>Santa Clara County</long_name>
            <short_name>Santa Clara County</short_name>
            <type>administrative_area_level_2</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>California</long_name>
            <short_name>CA</short_name>
            <type>administrative_area_level_1</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>United States</long_name>
            <short_name>US</short_name>
            <type>country</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>94043</long_name>
            <short_name>94043</short_name>
            <type>postal_code</type>
        </address_component>
        <geometry>
            <location>
                <lat>37.4224428</lat>
                <lng>-122.0842467</lng>
            </location>
            <location_type>ROOFTOP</location_type>
            <viewport>
                <southwest>
                    <lat>37.4212648</lat>
                    <lng>-122.0856069</lng>
                </southwest>
                <northeast>
                    <lat>37.4239628</lat>
                    <lng>-122.0829089</lng>
                </northeast>
            </viewport>
        </geometry>
        <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id>
        <plus_code>
            <global_code>849VCWC8+X8</global_code>
            <compound_code>CWC8+X8 Mountain View, CA</compound_code>
        </plus_code>
    </result>
</GeocodeResponse>

يُرجى العِلم بأنّ استجابة XML تتألّف من عنصر <GeocodeResponse> واحد وعنصرَين من المستوى الأعلى:

  • يحتوي <status> على بيانات وصفية في الطلب. ويمكنك الاطّلاع على رموز الحالة أدناه.
  • صفر أو أكثر من عناصر <result>، ويحتوي كل منها على مجموعة واحدة من معلومات العناوين المرمزة جغرافيًا والمعلومات الهندسية.

وتكون استجابة XML أطول بكثير من استجابة JSON. لهذا السبب، نقترح عليك استخدام json كعلامة الإخراج المفضّلة، ما لم تكن الخدمة تتطلب xml لسبب ما. بالإضافة إلى ذلك، تتطلّب معالجة أشجار XML بعض الحذر لكي تشير إلى العُقد والعناصر المناسبة. راجِع تحليل XML باستخدام XPath للتعرّف على بعض أنماط التصميم المقترَحة لمعالجة النتائج.

  • يتم تضمين نتائج XML في عنصر <GeocodeResponse> جذر.
  • تشير بيانات JSON إلى الإدخالات التي تتضمّن عناصر متعددة باستخدام صفائف الجمع (types)، بينما تشير لغة XML إلى هذه الإدخالات باستخدام عناصر مفرد متعددة (<type>).
  • تتم الإشارة إلى العناصر الفارغة من خلال صفائف فارغة في JSON، ولكن في حال عدم توفُّر أي من هذا العنصر في ملف XML. إذا لم يتم إنشاء أي نتائج، ستظهر مصفوفة results فارغة في JSON، ولكن لن يتم عرض عناصر <result> بتنسيق XML مثلاً.

رموز الحالة

يحتوي الحقل "status" ضمن كائن استجابة الترميز الجغرافي على حالة الطلب، وقد يحتوي على معلومات تصحيح الأخطاء لمساعدتك في تتبُّع سبب عدم عمل الترميز الجغرافي. قد يحتوي الحقل "status" على القيم التالية:

  • يشير "OK" إلى عدم حدوث أي أخطاء، حيث تم تحليل العنوان بنجاح وتم عرض رمز جغرافي واحد على الأقل.
  • يشير "ZERO_RESULTS" إلى أن الرمز الجغرافي كان ناجحًا ولكنه لم يعرض أي نتائج. قد يحدث هذا إذا تم تمرير رمز الموقع الجغرافي إلى address غير موجود.
  • تشير السمة OVER_DAILY_LIMIT إلى أيّ مما يلي:
    • مفتاح واجهة برمجة التطبيقات مفقود أو غير صالح.
    • لم يتم تفعيل الفوترة في حسابك.
    • تم تجاوز الحد الأقصى الذي تم فرضه ذاتيًا.
    • لم تعد طريقة الدفع المقدَّمة صالحة (على سبيل المثال، انتهت صلاحية بطاقة الائتمان).

    يمكنك الاطّلاع على الأسئلة الشائعة حول "خرائط Google" للتعرّف على كيفية حلّ هذه المشكلة.

  • يشير الرمز "OVER_QUERY_LIMIT" إلى أنّك تجاوزت مساحة التخزين المتوفّرة.
  • يشير الرقم "REQUEST_DENIED" إلى أنّه تم رفض طلبك.
  • تشير السمة "INVALID_REQUEST" بشكل عام إلى أنّ طلب البحث (address أو components أو latlng) غير متوفّر.
  • تشير السمة "UNKNOWN_ERROR" إلى أنّه تعذّرت معالجة الطلب بسبب خطأ في الخادم. قد ينجح الطلب إذا أعدت المحاولة.

رسائل الخطأ

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

النتائج

عندما يعرض الرمز الجغرافي النتائج، فإنه يضعها داخل مصفوفة results (JSON) حتى إذا لم يعرض الترميز الجغرافي أي نتائج (إذا لم يكن العنوان موجودًا مثلاً)، فإنه لا يزال يعرض مصفوفة results فارغة. (تتكون استجابات XML من صفر أو أكثر من عناصر <result>.)

تحتوي النتيجة النموذجية على الحقول التالية:

  • وتشير المصفوفة types[] إلى نوع النتيجة المعروضة. تحتوي هذه الصفيفة على مجموعة من العلامات الصفر أو أكثر تحدد نوع الميزة التي يتم عرضها في النتيجة. على سبيل المثال، يعرض الرمز الجغرافي لـ "شيكاغو" كلمة "المنطقة المحلية" التي تشير إلى أن "شيكاغو" مدينة، ويعرض أيضًا كلمة "سياسي" مما يدل على أنها كيان سياسي. قد تحتوي المكونات على مصفوفة أنواع فارغة عندما لا تكون هناك أنواع معروفة لمكون العنوان هذا. وقد تضيف واجهة برمجة التطبيقات قيم أنواع جديدة حسب الحاجة. لمزيد من المعلومات، يُرجى الاطِّلاع على أنواع العناوين ومكوّناتها.
  • formatted_address هي سلسلة تحتوي على العنوان الذي يمكن للمستخدمين قراءته لهذا الموقع الجغرافي.

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

    يتكون العنوان المنسَّق منطقيًا من مكوّن عنوان واحد أو أكثر. على سبيل المثال، يتكوّن العنوان "111 8th Africa, New York, NY" من المكونات التالية: "111" (رقم الشارع) و"8th Street" (المسار) و"New York" (المدينة) و "NY" (ولاية الولايات المتحدة).

    لا تحلّل العنوان المنسَّق آليًا. بدلاً من ذلك، عليك استخدام عناصر العنوان الفردية التي يتضمّنها ردّ واجهة برمجة التطبيقات بالإضافة إلى حقل العنوان المنسَّق.

  • address_components[] هي مصفوفة تحتوي على المكوّنات المنفصلة التي تنطبق على هذا العنوان.

    يحتوي كل مكون عنوان عادةً على الحقول التالية:

    • types[] هي مصفوفة تشير إلى نوع مكوّن العنوان. راجِع قائمة الأنواع المتوافقة.
    • long_name هو وصف النص الكامل أو اسم مكوّن العنوان كما يعرضه برنامج الترميز الجغرافي.
    • short_name هو اسم نصي مختصر لمكوِّن العنوان، في حال توفّره. على سبيل المثال، قد يحتوي عنصر عنوان لولاية ألاسكا على long_name للاسم "ألاسكا" وshort_name للرمز "AK" باستخدام الاختصار البريدي المكوّن من حرفَين.

    يُرجى الاطّلاع على المعلومات التالية حول مصفوفة address_components[]:

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

    للتعامل مع مصفوفة المكوّنات، عليك تحليل الإجابة واختيار القيم المناسبة من خلال التعبيرات. اطّلِع على دليل تحليل الردود.

  • postcode_localities[] هي مصفوفة تشير إلى ما يصل إلى 100 منطقة محلية مضمّنة في رمز بريدي. ولا يتوفّر هذا الخيار إلا عندما تكون النتيجة رمزًا بريديًا يحتوي على مناطق محلية متعددة.
  • يحتوي geometry على المعلومات التالية:
    • يحتوي location على قيمة خط الطول وخط العرض المرمزة جغرافيًا. بالنسبة إلى عمليات البحث عن العناوين العادية، يكون هذا الحقل عادةً هو الأكثر أهمية.

    • يُخزِّن location_type بيانات إضافية عن الموقع الجغرافي المحدَّد. يمكن استخدام القيم التالية في الوقت الحالي:

      • تشير السمة "ROOFTOP" إلى أنّ النتيجة المعروضة هي رمز جغرافي دقيق لدينا معلومات عن الموقع الجغرافي بدقة تصل إلى دقة عنوان الشارع.
      • تشير السمة "RANGE_INTERPOLATED" إلى أنّ النتيجة المعروضة تعكس تقديرًا تقريبيًا (عادةً على طريق) تم إدراجه بين نقطتين دقيقتَين (مثل التقاطعات). بشكل عام، يتم عرض النتائج التي تم إدخال قيمها المدخَلة عندما تكون الرموز الجغرافية للأسطح غير متاحة لعنوان شارع.
      • تشير السمة "GEOMETRIC_CENTER" إلى أنّ النتيجة المعروضة هي المركز الهندسي للنتيجة، مثل خط متعدد (شارع) أو مضلّع (منطقة).
      • تشير السمة "APPROXIMATE" إلى أنّ النتيجة المعروضة تقريبية.
    • يحتوي viewport على إطار العرض الذي يُنصح به لعرض النتيجة المعروضة، والمحددة كقيمتين لخط الطول وخط العرض تحددان الزاوية southwest وnortheast من مربع حدود إطار العرض. وبشكل عام، يتم استخدام إطار العرض لتحديد إطار نتيجة عند عرضها للمستخدم.
    • يخزِّن bounds (يتم إرجاعه اختياريًا) مربّع الإحاطة الذي يمكن أن يحتوي بالكامل على النتيجة المعروضة. وتجدُر الإشارة إلى أنّ هذه الحدود قد لا تتطابق مع إطار العرض المقترَح. (على سبيل المثال، تشتمل سان فرانسيسكو على جزر فارالون، التي تشكّل فعليًا جزءًا من المدينة، ولكن من المحتمل ألا يتم عرضها في إطار العرض).
  • plus_code (يُرجى الاطّلاع على Open Location Code (رمز الموقع المفتوح) وplus icon) هو مرجع موقع جغرافي مشفّر، مشتق من إحداثيات خطوط الطول والعرض، ويمثل مساحة: 1/8, 000 درجة مضروبة في 1/8, 000 درجة (حوالي 14 متر × 14 متر عند خط الاستواء) أو أقل. يمكن استخدام رموز المواقع المفتوحة كبديل لعناوين الشوارع في الأماكن التي لا توجد فيها العناوين (حيث لا تكون المباني مرقمة أو لا تتم تسمية الشوارع). لا تعرض واجهة برمجة التطبيقات دائمًا رموز المواقع المفتوحة.

    عندما تعرض الخدمة رمز الموقع المفتوح، يتم تنسيقه كرمز عام ورمز مركب:

    • global_code هو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (849VCWC8+R9).
    • compound_code هو رمز محلي أو أكثر يتألف من 6 أحرف مع موقع جغرافي صريح (CWC8+R9، ماونتن فيو، كاليفورنيا، الولايات المتحدة). يجب عدم تحليل هذا المحتوى آليًا.
    تعرض واجهة برمجة التطبيقات كلاً من الرمز العام والرمز المركَّب، في حال توفّرها. في المقابل، إذا كانت النتيجة في موقع جغرافي بعيد (مثل محيط أو صحراء)، قد يتم عرض الرمز العالمي فقط.

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

    غالبًا ما تحدث المطابقات الجزئية لعناوين الشوارع التي لا توجد ضمن المنطقة المحلية التي يتم تمريرها في الطلب. ويمكن أيضًا عرض المطابقات الجزئية عندما يتطابق الطلب مع موقعَين أو أكثر في المنطقة المحلية نفسها. على سبيل المثال، ستعرض نتائج البحث "Hillpar St, Bristol, UK" مطابقة جزئية لكل من شارع "هنري ستريت" و"شارع هنرييتا". لاحظ أنه إذا اشتمل الطلب على عنصر عنوان به خطأ إملائي، فقد تقترح خدمة الترميز الجغرافي عنوانًا بديلاً. سيتم أيضًا تمييز الاقتراحات التي يتم تنفيذها بهذه الطريقة على أنّها مطابقة جزئية.

  • السمة place_id هي معرّف فريد يمكن استخدامه مع واجهات Google APIs الأخرى. على سبيل المثال، يمكنك استخدام place_id في طلب Places API للحصول على تفاصيل حول نشاط تجاري محلي، مثل رقم الهاتف وساعات العمل ومراجعات المستخدمين وغير ذلك. اطّلِع على نظرة عامة على معرّف المكان.

أنواع العناوين وأنواع عناصر العناوين

تشير المصفوفة types[] في النتيجة إلى نوع العنوان. وتشمل أمثلة أنواع العناوين عنوان شارع أو بلدًا أو كيانًا سياسيًا. وتتوفر أيضًا مصفوفة types[] في address_components[]، للإشارة إلى نوع كل جزء من العنوان. وتشمل الأمثلة رقم الشارع أو البلد. (في ما يلي قائمة كاملة بالأنواع.) قد يكون للعناوين عدة أنواع. يمكن اعتبار الأنواع "علامات". على سبيل المثال، تتم الإشارة إلى العديد من المدن بالنوع political والنوع locality.

الأنواع التالية متوافقة وتعرضها أداة الترميز الجغرافي في كل من مصفوفات نوع العنوان ومكوِّن العنوان:

  • تشير السمة street_address إلى عنوان شارع دقيق.
  • تشير القيمة route إلى مسار يحمل اسمًا (مثل "US 101").
  • تشير السمة intersection إلى تقاطع رئيسي، يتألف عادةً من طريقَين رئيسيَين.
  • يشير الرمز political إلى كيان سياسي. يشير هذا النوع عادةً إلى شكل مضلّع خاص ببعض الإدارة المدنية.
  • يشير country إلى الكيان السياسي الوطني، ويكون عادةً أعلى نوع ترتيب يعرضه برنامج Geocoder.
  • تشير السمة administrative_area_level_1 إلى كيان مدني من الدرجة الأولى أسفل مستوى البلد. وداخل الولايات المتحدة، هذه المستويات الإدارية هي الولايات. لا تظهر هذه المستويات الإدارية في بعض الدول. في معظم الحالات، تتطابق الأسماء المختصرة في admin_area_level_1 بشكل وثيق مع الأقسام الفرعية وفقًا لمعيار ISO 3166-2 والقوائم التي يتم تداولها على نطاق واسع، إلا أنّ ذلك ليس مضمونًا لأنّ نتائج الترميز الجغرافي تستند إلى مجموعة متنوعة من الإشارات وبيانات الموقع الجغرافي.
  • تشير السمة administrative_area_level_2 إلى كيان مدني من الدرجة الثانية يندرج ضمن مستوى البلد. أمّا المستويات الإدارية داخل الولايات المتحدة، فهي مقاطعات. لا تظهر هذه المستويات الإدارية في بعض الدول.
  • تشير السمة administrative_area_level_3 إلى كيان مدني ذي مرتبة ثالثة أسفل مستوى البلد. يشير هذا النوع إلى تقسيم مدني صغير. لا تظهر هذه المستويات الإدارية في بعض الدول.
  • تشير السمة administrative_area_level_4 إلى كيان مدني من المستوى الرابع أسفل مستوى البلد. يشير هذا النوع إلى تقسيم مدني صغير. لا تظهر هذه المستويات الإدارية في بعض الدول.
  • تشير السمة administrative_area_level_5 إلى كيان مدني من الدرجة الخامسة أسفل مستوى البلد. يشير هذا النوع إلى تقسيم مدني صغير. لا تظهر هذه المستويات الإدارية في بعض الدول.
  • تشير السمة administrative_area_level_6 إلى كيان مدني من الدرجة السادسة أسفل مستوى البلد. يشير هذا النوع إلى تقسيم مدني صغير. لا تظهر هذه المستويات الإدارية في بعض الدول.
  • تشير السمة administrative_area_level_7 إلى كيان مدني من الدرجة السابعة أسفل مستوى البلد. يشير هذا النوع إلى تقسيم مدني صغير. لا تظهر هذه المستويات الإدارية في بعض الدول.
  • تشير السمة colloquial_area إلى الاسم البديل الشائع الاستخدام للكيان.
  • تشير السمة locality إلى كيان سياسي في مدينة أو بلدة مدمجة.
  • تشير السمة sublocality إلى كيان مدني من الدرجة الأولى أسفل المنطقة المحلية. بالنسبة إلى بعض المواقع الجغرافية، قد تتلقّى أحد الأنواع الإضافية: من sublocality_level_1 إلى sublocality_level_5. كل مستوى من مستويات المنطقة المحلية الفرعية هو كيان مدني. تشير الأرقام الأكبر إلى منطقة جغرافية أصغر.
  • تشير السمة neighborhood إلى حيّ معيَّن.
  • تشير السمة premise إلى موقع جغرافي مُسمّى، وعادةً ما يكون مبنى أو مجموعة من المباني ذات اسم شائع.
  • تشير السمة subpremise إلى كيان من الدرجة الأولى أسفل موقع جغرافي مسمّى، ويكون عادةً مبنى فرديًا داخل مجموعة من المباني ذات اسم شائع.
  • تشير السمة plus_code إلى مرجع موقع جغرافي مشفّر مشتق من خط العرض وخط الطول. يمكن استخدام رموز المواقع المفتوحة كبديل لعناوين الشوارع في الأماكن التي لا تتوفر فيها (حيث لا تكون المباني مرقمة أو لا تتم تسمية الشوارع). يمكنك الاطّلاع على https://plus.codes لمعرفة التفاصيل.
  • تشير السمة postal_code إلى الرمز البريدي على أنّه يُستخدَم لتوجيه البريد البريدي داخل البلد.
  • تشير السمة natural_feature إلى موضع طبيعي بارز.
  • تشير السمة airport إلى مطار.
  • تشير السمة park إلى متنزه معيَّن.
  • تشير القيمة point_of_interest إلى نقطة اهتمام مسماة. وعادةً ما تكون نقاط الاهتمام هذه كيانات محلية بارزة لا يمكن إدراجها بسهولة في فئة أخرى، مثل "مبنى إمباير ستيت" أو "برج إيفل".

تشير قائمة الأنواع الفارغة إلى عدم توفُّر أنواع معروفة لمكوِّن العنوان المحدّد، مثل Lieu-dit في فرنسا.

بالإضافة إلى ما سبق، قد تتضمن مكونات العنوان الأنواع المذكورة هنا. هذه القائمة ليست شاملة وقابلة للتغيير.

  • يشير floor إلى طابق عنوان المبنى.
  • تشير السمة establishment عادةً إلى مكان لم يتم تصنيفه بعد.
  • تشير السمة landmark إلى مكان مجاور يتم استخدامه كمرجع للمساعدة في التنقّل.
  • تشير القيمة point_of_interest إلى نقطة اهتمام مسماة.
  • تشير السمة parking إلى موقف سيارات أو موقف سيارات.
  • تشير السمة post_box إلى صندوق بريدي معيّن.
  • تشير السمة postal_town إلى مجموعة من المناطق الجغرافية، مثل locality وsublocality، المستخدَمة للعناوين البريدية في بعض البلدان.
  • تشير السمة room إلى غرفة عنوان المبنى.
  • تشير السمة street_number إلى رقم الشارع الدقيق.
  • يشير bus_station وtrain_station وtransit_station إلى الموقع الجغرافي لمحطة حافلات أو قطار أو نقل عام.

انحياز إطار العرض

في طلب الترميز الجغرافي، يمكنك توجيه خدمة الترميز الجغرافي لتفضيل النتائج ضمن إطار عرض معيّن (يتم التعبير عنه كمربّع محيط). يمكنك إجراء ذلك ضمن عنوان URL للطلب من خلال ضبط المَعلمة bounds.

تحدّد المعلَمة bounds إحداثيات خط العرض/خط الطول للزوايا الجنوبية الغربية والشمالية الشرقية لهذا المربّع المحيط باستخدام حرف الشرطة الرأسية (|) لفصل الإحداثيات.

على سبيل المثال، يشير الرمز الجغرافي لـ "واشنطن" بشكل عام إلى ولاية واشنطن الأمريكية:

الطلب:

https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY

الرد:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Washington",
               "short_name" : "WA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Washington, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 49.0024442,
                  "lng" : -116.91558
               },
               "southwest" : {
                  "lat" : 45.543541,
                  "lng" : -124.8489739
               }
            },
            "location" : {
               "lat" : 47.7510741,
               "lng" : -120.7401385
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 49.0024442,
                  "lng" : -116.91558
               },
               "southwest" : {
                  "lat" : 45.543541,
                  "lng" : -124.8489739
               }
            }
         },
         "place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
         "types" : [ "administrative_area_level_1", "political" ]
      }
   ],
   "status" : "OK"
}

في المقابل، إنّ إضافة الوسيطة bounds التي تحدّد مربّع الإحاطة حول الجزء الشمالي الشرقي من الولايات المتحدة تؤدي إلى ظهور هذا الرمز الجغرافي لمدينة واشنطن العاصمة:

الطلب:

https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY

الرد:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Washington",
               "short_name" : "Washington",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "District of Columbia",
               "short_name" : "District of Columbia",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "District of Columbia",
               "short_name" : "DC",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Washington, DC, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 38.9958641,
                  "lng" : -76.90939299999999
               },
               "southwest" : {
                  "lat" : 38.7916449,
                  "lng" : -77.119759
               }
            },
            "location" : {
               "lat" : 38.9071923,
               "lng" : -77.03687069999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 38.9958641,
                  "lng" : -76.90939299999999
               },
               "southwest" : {
                  "lat" : 38.7916449,
                  "lng" : -77.119759
               }
            }
         },
         "place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

انحياز المنطقة

في طلب الترميز الجغرافي، يمكنك توجيه خدمة الترميز الجغرافي لعرض النتائج المتحيزة لمنطقة معيّنة باستخدام المعلَمة region. تستخدم هذه المَعلمة وسيطة ccTLD (نطاق المستوى الأعلى لرمز البلد) التي تحدد انحياز المنطقة. تتطابق معظم رموز ccTLD مع رموز ISO 3166-1، مع بعض الاستثناءات الملحوظة. على سبيل المثال، يكون رمز ccTLD التابع للمملكة المتحدة هو "uk" (.co.uk) بينما يكون رمز ISO 3166-1 هو "gb" (من الناحية التقنية لكيان "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية").

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

على سبيل المثال، يعرض الرمز الجغرافي لـ "Toledo" هذه النتيجة، لأنّ النطاق التلقائي لواجهة برمجة التطبيقات Geocoding API مضبوط على الولايات المتحدة. الطلب:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY

الرد:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lucas County",
               "short_name" : "Lucas County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Ohio",
               "short_name" : "OH",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OH, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.454229
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            },
            "location" : {
               "lat" : 41.6639383,
               "lng" : -83.55521200000001
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.454229
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            }
         },
         "place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

سيؤدي طلب الترميز الجغرافي لـ "توليدو" مع region=es (إسبانيا) إلى عرض المدينة الإسبانية.

الطلب:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&region=es&key=YOUR_API_KEY

الرد:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "TO",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Castile-La Mancha",
               "short_name" : "CM",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0796176
               }
            },
            "location" : {
               "lat" : 39.8628316,
               "lng" : -4.027323099999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0796176
               }
            }
         },
         "place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

تصفية المكونات

وفي استجابة الترميز الجغرافي، يمكن لواجهة برمجة تطبيقات الترميز الجغرافي عرض نتائج العناوين المحصورة بمنطقة معيّنة. يمكنك تحديد التقييد باستخدام فلتر "components" يتكوّن الفلتر من قائمة تتضمّن component:value أزواج، مفصولة بشرطة (|). تتيح قيم الفلاتر استخدام أساليب التصحيح الإملائي والمطابقة الجزئية نفسها مثل طلبات الترميز الجغرافي الأخرى. إذا عثر المرمز الجغرافي على تطابق جزئي لفلتر مكون، فستحتوي الاستجابة على الحقل partial_match.

تشمل أنواع components التي يمكن فلترتها ما يلي:

  • تتطابق السمة postal_code مع postal_code وpostal_code_prefix.
  • تتطابق السمة country مع اسم البلد أو رمز البلد المكوّن من حرفَين وفقًا لمعيار ISO 3166-1. وتتّبع واجهة برمجة التطبيقات معيار ISO لتحديد البلدان، وتعمل الفلترة على النحو الأمثل عند استخدام رمز ISO المقابل للبلد.

يمكن استخدام components التالية للتأثير في النتائج، ولكن لن يتم فرضها:

  • يتطابق route مع الاسم الطويل أو المختصر للمسار.
  • يتطابق locality مع النوعَين locality وsublocality.
  • يتطابق administrative_area مع جميع مستويات administrative_area.

ملاحظات حول فلترة المكوِّن:

  • لا تكرِّر فلاتر المكوّنات هذه في الطلبات، وإلا ستعرض واجهة برمجة التطبيقات Invalid_request: country أو postal_code أو route.
  • إذا كان الطلب يحتوي على فلاتر مكوّنات متكرّرة، ستقيّم واجهة برمجة التطبيقات هذه الفلاتر على أنّها حرف AND وليس بالرمز OR.
  • تتوافق النتائج مع "خرائط Google"، ما يؤدي في بعض الأحيان إلى ظهور ردود ZERO_RESULTS غير متوقّعة. وقد يؤدي استخدام ميزة "الإكمال التلقائي" لميزة "الأماكن" إلى توفير نتائج أفضل في بعض حالات الاستخدام. للحصول على مزيد من المعلومات، يمكنك الاطّلاع على هذه الأسئلة الشائعة.
  • بالنسبة إلى كل مكوّن عنوان، حدِّده في المعلَمة address أو في فلتر components، ولكن ليس في كليهما. قد يؤدي تحديد القيم نفسها في كلتا القيمتين إلى ظهور ZERO_RESULTS.

الرمز الجغرافي لـ "هايستينغز، هاستينغز" مع components=country:GB يعرض نتيجة في هاستينغز، إنجلترا بدلاً من هاستينغز-أون هدسون، الولايات المتحدة الأمريكية.

الطلب:

https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY

الرد:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "High Street",
               "short_name" : "High St",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Hastings",
               "short_name" : "Hastings",
               "types" : [ "postal_town" ]
            },
            {
               "long_name" : "East Sussex",
               "short_name" : "East Sussex",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "England",
               "short_name" : "England",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United Kingdom",
               "short_name" : "GB",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "TN34 3EY",
               "short_name" : "TN34 3EY",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "High St, Hastings TN34 3EY, UK",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 50.8601041,
                  "lng" : 0.5957329
               },
               "southwest" : {
                  "lat" : 50.8559061,
                  "lng" : 0.5906163
               }
            },
            "location" : {
               "lat" : 50.85830319999999,
               "lng" : 0.5924594
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 50.8601041,
                  "lng" : 0.5957329
               },
               "southwest" : {
                  "lat" : 50.8559061,
                  "lng" : 0.5906163
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}

طلب رمز جغرافي لمنطقة "سانتا كروز" مع components=country:ES إرجاع "سانتا كروز دي تينيريفي" في جزر الكناري في إسبانيا.

الطلب:

https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY

الرد:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "Santa Cruz de Tenerife",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "TF",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Canary Islands",
               "short_name" : "CN",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Santa Cruz de Tenerife, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            },
            "location" : {
               "lat" : 28.4636296,
               "lng" : -16.2518467
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            }
         },
         "place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

لا تعرض فلترة المكونات استجابة ZERO_RESULTS إلا إذا قدَّمت فلاتر تستبعد بعضها البعض.

الطلب:

https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY

الرد:

{
   "results" : [],
   "status" : "ZERO_RESULTS"
}

يمكنك إجراء طلبات بحث صالحة بدون معلَمة العنوان باستخدام الفلتر components. (عند الترميز الجغرافي لعنوان كامل، تكون المعلمة address مطلوبة إذا كان الطلب يحتوي على أسماء المباني وأرقامها).

الطلب:

https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY

الرد:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Annankatu",
               "short_name" : "Annankatu",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsinki",
               "short_name" : "HKI",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "00101",
               "short_name" : "00101",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Annankatu, 00101 Helsinki, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9433353
               },
               "southwest" : {
                  "lat" : 60.16226160000001,
                  "lng" : 24.9332897
               }
            },
            "location" : {
               "lat" : 60.1657808,
               "lng" : 24.938451
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9433353
               },
               "southwest" : {
                  "lat" : 60.16226160000001,
                  "lng" : 24.9332897
               }
            }
         },
         "place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}