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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

طلب

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

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

حيث قد يكون outputFormat أيًا من القيم التالية:

  • json (مُقترَح) تشير إلى ناتج في JavaScript Object Notation (JSON)، أو
  • xml يشير إلى XML في XML

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

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

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

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

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

  • address — عنوان الشارع أو رمز Plus Codes الذي تريد ترميزه جغرافيًا. ويجب تحديد العناوين وفقًا للتنسيق الذي تستخدمه الخدمة البريدية الوطنية في البلد المعني. ويجب تجنّب عناصر العنوان الإضافية، مثل أسماء الأنشطة التجارية والوحدات أو أرقام الجناح أو الطابق. يجب الفصل بين عناصر عناوين الشوارع بمسافات (تظهر هنا كعناصر إلغاء عنوان URL إلى %20):
    address=24%20Sussex%20Drive%20Ottawa%20ON
    يجب تنسيق رموز Plus Codes كما هو موضّح هنا (علامات الإلغاء من عناوين URL تتضمّن عناوين 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 لطلب بحث عن رقم تعريف المكان "ChIJeRpOeF67j4AR9ydy_PIzPuM"، وهو المكان للمبنى في 1600 Amphitheatre Parkway, Mountain View, CA.

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

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[] إلى type للنتيجة المعروضة. تحتوي هذه المصفوفة على مجموعة صفرية أو أكثر من العلامات التي تحدّد نوع الميزة المعروضة في النتيجة. على سبيل المثال، يشير ترميز جغرافي عن "شيكاغو" إلى "المنطقة المحلية" التي تشير إلى أن "شيكاغو" مدينة، وتعرض أيضًا "السياسة" والتي تشير إلى أنها كيان سياسي.
  • formatted_address عبارة عن سلسلة تحتوي على عنوان يمكن للمستخدمين قراءته لهذا الموقع الجغرافي.

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

    يتألّف العنوان المنسّق منطقيًا من مكوّن عنوان واحد أو أكثر. على سبيل المثال، يتألف العنوان "111 شارع 8، نيويورك، نيويورك" من المكونات التالية: "111" (رقم الشارع)، و"جادة 8" (المسار) و"نيويورك" (المدينة) و"نيويورك" (ولاية الولايات المتحدة).

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

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

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

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

    يُرجى ملاحظة الحقائق التالية حول المصفوفة address_components[]:

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

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

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

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

    يتم تنسيق رمز Plus Codes كرمز عام ورمز مركّب:

    • global_code هو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (849VCWC8+R9).
    • compound_code هو رمز محلي مكوَّن من 6 أحرف أو أكثر يتضمّن موقعًا جغرافيًا فاضحًا (CWC8+R9 و Mountain View وCA, USA). عدم تحليل هذا المحتوى آليًا
    يتم عادةً عرض كل من الرمز العام والرمز المركّب. ومع ذلك، إذا كانت النتيجة في موقع ناءٍ (على سبيل المثال، محيط أو صحراء)، لا يمكن عرض سوى الرمز العالمي.
  • يشير partial_match إلى أن أداة ترميز البيانات لم تعرض مطابقة تامة للطلب الأصلي، على الرغم من أنها تمكّنت من مطابقة جزء من العنوان المطلوب. ننصحك بفحص الطلب الأصلي بحثًا عن أخطاء إملائية و/أو عنوان غير مكتمل.

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

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

أنواع العناوين وأنواع مكوّنات العنوان

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

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

  • يشير street_address إلى عنوان شارع دقيق.
  • يشير route إلى مسار مُسمى (مثل "US 101").
  • تشير علامة intersection إلى تقاطع طرق رئيسي، وعادةً ما يتألف من طريقين رئيسيين.
  • يشير political إلى كيان سياسي. ويشير هذا النوع عادةً إلى مضلّع محدّد للإدارة المدنية.
  • ويشير country إلى الكيان السياسي الوطني، وهو عادةً أعلى نوع ترتيب يعرضه الموقع الجغرافي.
  • يشير administrative_area_level_1 إلى كيان مدني من الدرجة الأولى أسفل مستوى البلد. تقع هذه المستويات الإدارية داخل الولايات المتحدة. يُرجى العِلم أنّه لا يتم عرض هذه المستويات الإدارية في جميع البلدان. في معظم الحالات، ستتطابق الأسماء الإدارية_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 إلى مرجع موقع مشفّر، مشتق من خط الطول وخط العرض. يمكن استخدام رموز Plus Codes كبديل لعناوين الشوارع في الأماكن التي لا توجد فيها (حيث لا يتم ترقيم المباني أو عدم تسمية الشوارع). يمكنك الاطّلاع على 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"
}