تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

الطلب

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

JSON

{
    "results": [
        {
            "address_components": [
                {
                    "long_name": "1600",
                    "short_name": "1600",
                    "types": [
                        "street_number"
                    ]
                },
                {
                    "long_name": "Amphitheatre Parkway",
                    "short_name": "Amphitheatre Pkwy",
                    "types": [
                        "route"
                    ]
                },
                {
                    "long_name": "Mountain View",
                    "short_name": "Mountain View",
                    "types": [
                        "locality",
                        "political"
                    ]
                },
                {
                    "long_name": "Santa Clara County",
                    "short_name": "Santa Clara County",
                    "types": [
                        "administrative_area_level_2",
                        "political"
                    ]
                },
                {
                    "long_name": "California",
                    "short_name": "CA",
                    "types": [
                        "administrative_area_level_1",
                        "political"
                    ]
                },
                {
                    "long_name": "United States",
                    "short_name": "US",
                    "types": [
                        "country",
                        "political"
                    ]
                },
                {
                    "long_name": "94043",
                    "short_name": "94043",
                    "types": [
                        "postal_code"
                    ]
                },
                {
                    "long_name": "1351",
                    "short_name": "1351",
                    "types": [
                        "postal_code_suffix"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
            "geometry": {
                "location": {
                    "lat": 37.4222804,
                    "lng": -122.0843428
                },
                "location_type": "ROOFTOP",
                "viewport": {
                    "northeast": {
                        "lat": 37.4237349802915,
                        "lng": -122.083183169709
                    },
                    "southwest": {
                        "lat": 37.4210370197085,
                        "lng": -122.085881130292
                    }
                }
            },
            "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8",
            "plus_code": {
                "compound_code": "CWC8+W7 Mountain View, CA",
                "global_code": "849VCWC8+W7"
            },
            "types": [
                "street_address"
            ]
        }
    ],
    "status": "OK"
}

تجدر الإشارة إلى أنّ استجابة JSON تحتوي على عنصرَين أساسيَين:

يحتوي "status" على بيانات وصفية عن الطلب. يمكنك الاطّلاع على رموز الحالة أدناه.
يحتوي "results" على صفيف من معلومات العناوين الترميز الجغرافي ومعلومات الشكل الهندسي.

بشكل عام، يتم عرض إدخال واحد فقط في صفيف "results" عند البحث عن addresses، على الرغم من أنّ المعرِّف الجغرافي قد يعرض عدة نتائج عندما تكون طلبات البحث عن addresses غامضة.

XML

<GeocodeResponse>
    <status>OK</status>
    <result>
        <type>street_address</type>
        <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address>
        <address_component>
            <long_name>1600</long_name>
            <short_name>1600</short_name>
            <type>street_number</type>
        </address_component>
        <address_component>
            <long_name>Amphitheatre Parkway</long_name>
            <short_name>Amphitheatre Pkwy</short_name>
            <type>route</type>
        </address_component>
        <address_component>
            <long_name>Mountain View</long_name>
            <short_name>Mountain View</short_name>
            <type>locality</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>Santa Clara County</long_name>
            <short_name>Santa Clara County</short_name>
            <type>administrative_area_level_2</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>California</long_name>
            <short_name>CA</short_name>
            <type>administrative_area_level_1</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>United States</long_name>
            <short_name>US</short_name>
            <type>country</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>94043</long_name>
            <short_name>94043</short_name>
            <type>postal_code</type>
        </address_component>
        <geometry>
            <location>
                <lat>37.4224428</lat>
                <lng>-122.0842467</lng>
            </location>
            <location_type>ROOFTOP</location_type>
            <viewport>
                <southwest>
                    <lat>37.4212648</lat>
                    <lng>-122.0856069</lng>
                </southwest>
                <northeast>
                    <lat>37.4239628</lat>
                    <lng>-122.0829089</lng>
                </northeast>
            </viewport>
        </geometry>
        <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id>
        <plus_code>
            <global_code>849VCWC8+X8</global_code>
            <compound_code>CWC8+X8 Mountain View, CA</compound_code>
        </plus_code>
    </result>
</GeocodeResponse>

يُرجى العِلم أنّ استجابة XML تتكوّن من <GeocodeResponse> واحد وعنصرَين من المستوى الأعلى:

يحتوي <status> على بيانات وصفية عن الطلب. يمكنك الاطّلاع على رموز الحالة أدناه.
صفر أو أكثر من عناصر <result>، يحتوي كلّ منها على مجموعة واحدة من معلومات العناوين المُشفَّرة جغرافيًا ومعلومات الأشكال الهندسية

استجابة XML أطول بكثير من استجابة JSON. لهذا السبب، ننصح باستخدام json كعلامة الإخراج المفضّلة ما لم تكن خدمتك تتطلّب xml لسبب ما. بالإضافة إلى ذلك، تتطلّب معالجة أشجار XML بعض الحذر، حتى تتمكّن من الإشارة إلى العقد والعناصر المناسبة. اطّلِع على تحليل ملف XML باستخدام XPath لمعرفة بعض أنماط التصميم المقترَحة لمعالجة النتائج.

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

رموز الحالة

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

يشير الرمز "OK" إلى عدم حدوث أي أخطاء، فقد تم تحليل العنوان بنجاح وتم عرض رمز جغرافي واحد على الأقل.
يشير الرمز "ZERO_RESULTS" إلى أنّه تمّ استخدام الرمز الجغرافي بنجاح ولكنّه لم يعرض أي نتائج. قد يحدث ذلك إذا تم تمرير address غير متوفّر إلى أداة ترميز المواقع الجغرافية.
يشير الرمز OVER_DAILY_LIMIT إلى أيّ مما يلي:
- مفتاح واجهة برمجة التطبيقات غير متوفّر أو غير صالح.
- لم يتم تفعيل ميزة الفوترة في حسابك.
- تم تجاوز الحد الأقصى للاستخدام الذي فرضته على نفسك.
- لم تعُد طريقة الدفع المقدَّمة صالحة (على سبيل المثال، انتهت صلاحية بطاقة الائتمان).
اطّلِع على الأسئلة الشائعة حول "خرائط 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, Mountain View, CA, USA). لا تُحلِّل هذا المحتوى آليًا.
تعرض واجهة برمجة التطبيقات كلاً من الرمز الشامل والرمز المركب، حيثما كان ذلك متاحًا. ومع ذلك، إذا كانت النتيجة في موقع بعيد (مثل محيط أو صحراء)، قد يتم عرض الرمز العميق فقط.
يشير الرمز partial_match إلى أنّ أداة ترميز المواقع الجغرافية لم تعرِض مطابقة تامّة للطلب الأصلي، إلا أنّها تمكّنت من مطابقة جزء من العنوان المطلوب. ننصحك بمراجعة الطلب الأصلي بحثًا عن أخطاء إملائية و/أو عنوان غير مكتمل.

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

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

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

"DRIVE" هو وضع التنقّل المرتبط باتجاهات القيادة.
"WALK" هو وضع التنقّل المرتبط باتجاهات المشي.

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

تشير صفيف 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 المقابل للبلد.
ملاحظة: إذا تلقّيت نتائج غير متوقّعة باستخدام رمز بلد، تأكَّد من أنّك تستخدم رمزًا يتضمّن البلدان والأقاليم التابعة والمناطق الخاصة ذات الاهتمام الجغرافي التي تريدها. يمكنك العثور على معلومات عن الرموز على Wikipedia: List of ISO 3166 country codes أو ISO Online Browsing Platform.

يمكن استخدام 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"
}

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

الطلب

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

الردود

JSON

XML

رموز الحالة

رسائل الخطأ

النتائج

نقاط التنقّل

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

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

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

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