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

الطلب

يظهر طلب Geocoding API على النحو التالي:

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
     يجب تنسيق رموز Plus Codes كما هو موضّح هنا (يتم تخطي عنوان URL إلى %2B والمسافات إلى %20):
    • الرمز العام هو رمز منطقة مكوّن من 4 أحرف و6 أحرف أو أكثر. الرمز المحلي (849VCWC8+R9 هو 849VCWC8%2BR9).
    • الرمز المركب هو رمز محلي مكوَّن من 6 أحرف أو أكثر، الموقع الجغرافي الفاضح (CWC8+R9 Mountain View، كاليفورنيا، الولايات المتحدة الأمريكية هو 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"، وحظر النتائج تمامًا من أداة الترميز الجغرافي. الاطّلاع على مزيد من المعلومات عن فلترة المكوّنات أدناه.
  • extra_computations — استخدِم هذه المَعلمة لتحديد الميزات الإضافية التالية في الرد: لتفعيل عدّة ميزات من هذه الميزات لطلب البيانات من واجهة برمجة التطبيقات نفسه، أدرِج المَعلمة extra_computations في طلب كل ميزة، على سبيل المثال: 
    extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

الردود

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

في هذا المثال، تطلب Geocoding API json استجابة لطلب بحث عن العنوان "1600 Amphitheatre Parkway, Mountain View CA".

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

https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

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

https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&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"
                    ]
                },
                {
                    "long_name": "1351",
                    "short_name": "1351",
                    "types": [
                        "postal_code_suffix"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
            "geometry": {
                "location": {
                    "lat": 37.4222804,
                    "lng": -122.0843428
                },
                "location_type": "ROOFTOP",
                "viewport": {
                    "northeast": {
                        "lat": 37.4237349802915,
                        "lng": -122.083183169709
                    },
                    "southwest": {
                        "lat": 37.4210370197085,
                        "lng": -122.085881130292
                    }
                }
            },
            "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8",
            "plus_code": {
                "compound_code": "CWC8+W7 Mountain View, CA",
                "global_code": "849VCWC8+W7"
            },
            "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 إلى أي مما يلي:
    • مفتاح واجهة برمجة التطبيقات مفقود أو غير صالح.
    • لم يتم تفعيل الفوترة في حسابك.
    • تم تجاوز الحد الأقصى المسموح به للاستخدام.
    • لم تعُد طريقة الدفع المقدَّمة صالحة (على سبيل المثال، انتهت صلاحية بطاقة الائتمان).

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

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

رسائل الخطأ

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

النتائج

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

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

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

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

    يتكون العنوان بالتنسيق منطقيًا من عنوان واحد أو أكثر . على سبيل المثال، العنوان "111 8th Avenue, New York, NY" تتكون من المكونات التالية: "111" (رقم الشارع)، "الجادة 8" (المسار)، "نيويورك" (المدينة) و"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 (الاطّلاع على فتح رمز الموقع الجغرافي ورموز المواقع الإضافية) مشفّرة. مرجع الموقع، المستمد من إحداثيات خطوط الطول والعرض، التي يمثل مساحة: 1/8000 من الدرجة × 1/8000 من الدرجة (حوالي 14 متر × 14 متر عند خط الاستواء) أو أصغر. يمكن استخدام رموز Plus Codes كبديل عناوين الشوارع في أماكن لا توجد فيها العناوين (حيث لا توجد المباني) مرقمة أو لم يتم تسمية الشوارع). لا تعرض واجهة برمجة التطبيقات دائمًا رموز المواقع المفتوحة.

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

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

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

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

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

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

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

يتم دعم الأنواع التالية وعرضها بواسطة برنامج الترميز الجغرافي في كلٍ من صفائف نوع العنوان ونوع مكوِّن العنوان:

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

الانحياز إلى منطقة معيّنة

في طلب Geocoding، يمكنك توجيه خدمة Geocoding للعودة نتائج متحيزة لمنطقة معينة باستخدام region . تستخدم هذه المعلمة ccTLD (المستوى الأعلى لرمز البلد) domain) لتحديد تحيز المنطقة. تتطابق معظم رموز نطاقات المستوى الأعلى التي يتم ترميزها حسب البلد (ccTLD) مع رموز ISO 3166-1، مع بعض الاستثناءات الملحوظة. على سبيل المثال، تستخدم مؤسسة United اسم نطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (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"
}

فلترة المكوّنات

في استجابة Geocoding API، يمكن لواجهة Geocoding API عرض العنوان نتائج البحث في منطقة معينة. يمكنك تحديد القيود باستخدام فلتر 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"
}