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

الطلب

يظهر طلب 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 داخل كائن الاستجابة "ترميز جغرافي". يحتوي هذا الحقل على المزيد معلومات تفصيلية حول أسباب رمز الحالة المحدّد.

النتائج

عندما يعرض برنامج الترميز الجغرافي النتائج، يضعها في ملف (JSON) results. صفيفة. حتى إذا لم يعرض برنامج الترميز الجغرافي أي نتائج (مثلاً، إذا لم يكن العنوان موجودًا)، فإنه سيظل تعرض صفيفة 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 APIs الأخرى. على سبيل المثال، يمكنك استخدام 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"
}

طلب ترميز جغرافي لأغنية Toledo مع "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"
}