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

الطلب

يظهر طلب 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

  تنسيق رموز المواقع المفتوحة كما هو موضّح هنا (يتم تخطي عنوان URL إلى %2B باستخدام علامات الجمع ويتم تخطي عنوان URL والمسافات إلى %20):
  • الرمز العالمي هو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (رمز 849VCWC8+R9 هو 849VCWC8%2BR9).
  • الرمز المركب هو رمز محلي مكوَّن من 6 أحرف أو أكثر مع موقع جغرافي واضح (CWC8+R9 ماونتن فيو، كاليفورنيا، الولايات المتحدة الأمريكية هو CWC8%2BR9%20Mountain%20View%20CA%20USA).
  
  --أو--
  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" في كائن الاستجابة Geocoding حالة الطلب، وقد يحتوي على معلومات تصحيح الأخطاء لمساعدتك في تعقب سبب عدم عمل الترميز الجغرافي. قد يحتوي الحقل "status" على القيم التالية:

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

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

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

رسائل الخطأ

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

النتائج

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

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

• تشير المصفوفة types[] إلى type للنتيجة المعروضة. تحتوي هذه المصفوفة على مجموعة من علامات صفرية أو أكثر تحدّد نوع العنصر الذي يتم عرضه في النتيجة. على سبيل المثال، يعرض الرمز الجغرافي لمدينة "القاهرة" "locality" الذي يشير إلى أنّ "القاهرة" هي مدينة، ويعرض أيضًا "political" الذي يشير إلى أنّها كيان سياسي. قد يكون للمكونات مصفوفة أنواع فارغة عندما لا تكون هناك أنواع معروفة لمكون العنوان هذا. قد تضيف واجهة برمجة التطبيقات قيم أنواع جديدة حسب الحاجة. لمزيد من المعلومات، يُرجى الاطّلاع على أنواع العناوين وعناصرها.
• تمثّل 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 (يُرجى الاطّلاع على رمز الموقع الجغرافي المفتوح ورموز المواقع الجغرافية) هو مرجع مشفّر للموقع الجغرافي، وهو مشتق من إحداثيات خطوط الطول والعرض، ويمثّل المنطقة: 1/8, 000 درجة x 1, 8000 درجة (حوالي 14 متر x 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[]، تشير إلى نوع كل جزء من العنوان. وتشمل الأمثلة رقم الشارع أو البلد. (في ما يلي قائمة كاملة بالأنواع). وقد تحتوي العناوين على أنواع متعددة. ويمكن تصنيف هذه الأنواع على أنّها "علامات". على سبيل المثال، يتم وضع علامة على العديد من المدن باستخدام النوعَين 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"
}

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

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

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