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

الطلب

يأخذ طلب Geocoding API الشكل التالي:

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

حيث يمكن أن يكون outputFormat أيًّا من القيمتَين التاليتَين:

• json (مُستحسَن) يشير إلى الإخراج بتنسيق JavaScript Object Notation ‏ (JSON)
• يشير الرمز xml إلى الإخراج بتنسيق XML.

يجب استخدام بروتوكول HTTPS.

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

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

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

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

• key: مفتاح واجهة برمجة التطبيقات لتطبيقك. يحدِّد هذا المفتاح تطبيقك لأغراض إدارة الحصة. تعرَّف على كيفية الحصول على مفتاح.

• يجب تحديد address أو components أو كليهما في الطلب:

  • address: عنوان الشارع أو رمز الموقع المفتوح الذي تريد تحويله إلى رمز جغرافي حدِّد العناوين وفقًا للتنسيق الذي تستخدمه الخدمة البريدية الوطنية في البلد المعني. يجب تجنُّب استخدام عناصر العنوان الإضافية، مثل أسماء الأنشطة التجارية وأرقام الوحدات أو الأجنحة أو الطوابق. يجب الفصل بين عناصر عنوان الشارع بفواصل (معروضة هنا على أنّها مشفّرة بترميز URL إلى %20):

    address=24%20Sussex%20Drive%20Ottawa%20ON

    يجب تنسيق رموز Plus Codes كما هو موضّح هنا (يتم ترميز علامات الجمع إلى %2B في عنوان URL ويتم ترميز المسافات إلى %20):
    • الرمز العالمي هو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (849VCWC8+R9 هو 849VCWC8%2BR9).
    • الرمز المركب هو رمز محلي مكوّن من 6 أحرف أو أكثر يحدد موقعًا جغرافيًا واضحًا (CWC8+R9 Mountain View, CA, USA هو CWC8%2BR9%20Mountain%20View%20CA%20USA).
  • components: فلتر مكوّنات يتضمّن عناصر مفصولة بفاصل (|). يتم أيضًا قبول فلتر المكوّنات كمَعلمة اختيارية في حال توفّر address. يتكوّن كل عنصر في فلتر المكوّنات من component:value، ويحدّ من النتائج من المعرّف الجغرافي بالكامل. يمكنك الاطّلاع على مزيد من المعلومات عن فلترة المكوّنات أدناه.

اطّلِع على الأسئلة الشائعة للحصول على إرشادات إضافية.

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

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

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

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

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

• 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 (راجِع رمز الموقع المفتوح ورموز Plus Codes) هو مرجع موقع جغرافي مشفَّر، يتم الحصول عليه من إحداثيات خطوط الطول والعرض، ويمثّل منطقة: 1/8000 من الدرجة في 1/8000 من الدرجة (حوالي 14 مترًا في 14 مترًا عند خط الاستواء) أو أصغر. يمكن استخدام رموز Plus Codes كبديل لعناوين الشوارع في الأماكن التي لا تتوفّر فيها عناوين (حيث لا يتم ترقيم المباني أو تسمية الشوارع). لا تعرض واجهة برمجة التطبيقات رموز Plus Codes في بعض الأحيان.

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

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

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

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

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

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

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

تتيح خدمة الترميز الجغرافي الأنواع التالية وتُرجعها في كلّ من صفيفَي نوع العنوان ونوع عنصر العنوان:

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

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

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

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

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

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

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

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

الطلب:

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

الردّ:

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

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

الطلب:

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

الردّ:

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

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

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

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

على سبيل المثال، يعرض رمز جغرافي لمدينة "تولّدو" هذه النتيجة، لأنّ النطاق التلقائي لواجهة برمجة التطبيقات 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. يتألّف الفلتر من قائمة ب 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
• إذا كان الطلب يحتوي على فلاتر مكوّنات متكرّرة، تقيِّم واجهة برمجة التطبيقات تلك الفلاتر على أنّها عملية "و"، وليس "أو".
• تتطابق النتائج مع "خرائط Google"، التي تؤدي أحيانًا إلى ظهور ردود ZERO_RESULTS غير متوقّعة. قد يؤدي استخدام ميزة "الإكمال التلقائي للأماكن" إلى تقديم نتائج أفضل في بعض حالات الاستخدام. لمزيد من المعلومات، يُرجى الاطّلاع على هذه السلسلة من الأسئلة الشائعة.
• لكل مكوّن من مكوّنات العنوان، حدِّده في المَعلمة address أو في فلتر components، ولكن ليس كليهما. قد يؤدي تحديد القيم نفسها في كلا الحقلين إلى ظهور ZERO_RESULTS.

يعرض الرمز الجغرافي لـ "High St, Hastings" مع 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"
}