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

الطلب

يظهر طلب 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: استخدِم هذه المَعلمة لتحديد الميزات الإضافية التالية في الاستجابة:
  • ADDRESS_DESCRIPTORS — الاطّلاع واصفات العناوين لمزيد من التفاصيل.
  • BUILDING_AND_ENTRANCES — الاطّلاع والمداخل ومخطّطات المباني لمزيد من التفاصيل.
  لتفعيل العديد من هذه الميزات لطلب البيانات من واجهة برمجة التطبيقات نفسه، يجب تضمين معلَمة 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.

{
    "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"
}

<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>

رموز الحالة

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

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

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

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

رسائل الخطأ

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

النتائج

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

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

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

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

  يتألّف العنوان المنسَّق منطقيًا من مكوّن عنوان واحد أو أكثر. على سبيل المثال، العنوان "111 8th 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"
}

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

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