Method: resolveNames

تحوّل هذه الطريقة قائمة بأسماء الأماكن (أو العناوين) إلى كيانات جغرافية مكانية محدّدة (مثل الأماكن) على "خرائط Google".

طلب HTTP

POST https://mapstools.googleapis.com/v1alpha:resolveNames

يستخدِم عنوان URL بنية تحويل الترميز إلى gRPC.

نص الطلب

يتضمن نص الطلب بيانات بالبنية التالية:

تمثيل JSON 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
الحقول
queries[]

object (LocationQuery)

الحقل مطلوب. قائمة بطلبات البحث عن المواقع الجغرافية التي سيتم حلّها. يمكنك تحديد ما يصل إلى 20 طلب بحث.
locationBias

object (LocationBias)

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

في حال تحديد كل من locationBias وregionCode، تكون الأولوية لـ locationBias على regionCode.
regionCode

string

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

في حال تحديد كل من locationBias وregionCode، تكون الأولوية لـ locationBias على regionCode.

نص الاستجابة

رسالة الرد على v1alpha.resolveNames

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل JSON 
{
  "results": [
    {
      object (Result)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  }
}
الحقول
results[]

object (Result)

النتائج فقط. قائمة بالكيانات التي تم حلّها من طلبات البحث عن المواقع الجغرافية يتم ضمان مطابقة 1:1 مع فهارس الطلب queries. يشير السلسلة الفارغة في الفهرس i إلى تعذُّر التحويل لهذا الطلب. في حال تعذُّر إكمال عملية التحويل، يُرجى التحقّق من الحقل failedRequests لمعرفة حالة الخطأ.
failedRequests

map (key: integer, value: object (Status))

النتائج فقط. خريطة توضّح حالات الفشل الجزئية المفتاح هو فهرس الطلب الذي تعذّر تنفيذه في الحقل queries. القيمة هي حالة الخطأ التي توضّح سبب تعذُّر إكمال عملية التحويل.

عنصر يحتوي على قائمة بأزواج "key": value مثال: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

نطاقات الأذونات

يجب توفير أحد نطاقات OAuth التالية:

  • https://www.googleapis.com/auth/maps-platform.mapstools
  • https://www.googleapis.com/auth/cloud-platform.read-only

LocationQuery

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

تمثيل JSON 
{
  "text": string
}
الحقول
text

string

الحقل مطلوب. طلب البحث النصي الذي سيتم تحويله إلى كيان جغرافي مكاني محدّد على "خرائط Google"، مثل مكان أو عنوان كلما كان طلب البحث أكثر تحديدًا، كانت عملية الحل أكثر دقة. على سبيل المثال، "سان فرانسيسكو" أو "Googleplex، ماونتن فيو، كاليفورنيا" أو "1600 Amphitheatre Parkway، ماونتن فيو، كاليفورنيا" أو "برج إيفل، باريس". يجب أن تكون طلبات البحث عبارة عن عنوان أو اسم مكان محدّد. لا تتوفّر المواقع الجغرافية العامة، مثل اسم سلسلة متاجر (مثل Starbucks) أو طلب بحث مثل "مطاعم".

LocationBias

المنطقة التي يجب أن تكون نتائج درجة الدقة متوافقة معها

تمثيل JSON 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
الحقول
حقل الربط type تمثّل هذه السمة نوع التحيز المرتبط بالموقع الجغرافي. يمكن أن يكون التعليق type إحدى القيم التالية فقط:
viewport

object (Viewport)

إطار عرض محدّد بمربع إحاطة

إطار العرض

إطار عرض لخطوط الطول والعرض، ويتم تمثيله بنقطتَي low وhigh متقابلتَين قطريًا. يُعدّ إطار العرض منطقة مغلقة، أي أنّه يشمل حدوده. يجب أن تتراوح حدود خط العرض بين 90- و90 درجة شاملة، ويجب أن تتراوح حدود خط الطول بين 180- و180 درجة شاملة. تشمل الحالات المختلفة ما يلي:

  • إذا كان low = high، يتألف إطار العرض من تلك النقطة الواحدة.

  • إذا كانت قيمة low.longitude أكبر من high.longitude، يكون نطاق خط الطول معكوسًا (أي أنّ إطار العرض يتقاطع مع خط الطول 180 درجة).

  • إذا كانت low.longitude = -180 درجة وhigh.longitude = 180 درجة، ستشمل نافذة العرض جميع خطوط الطول.

  • إذا كانت low.longitude = 180 درجة وhigh.longitude = -180 درجة، سيكون نطاق خط الطول فارغًا.

  • إذا كانت قيمة low.latitude أكبر من high.latitude، يكون نطاق خطوط العرض فارغًا.

يجب ملء كلّ من low وhigh، ولا يمكن أن يكون المربع الممثَّل فارغًا (كما هو محدّد في التعريفات أعلاه). سيؤدي عرض إطار عرض فارغ إلى حدوث خطأ.

على سبيل المثال، تحتوي مساحة العرض هذه على مدينة نيويورك بالكامل:

{ "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } }

تمثيل JSON 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
الحقول
low

object (LatLng)

الحقل مطلوب. النقطة السفلية لإطار العرض
high

object (LatLng)

الحقل مطلوب. النقطة العليا من إطار العرض

LatLng

كائن يمثّل زوج خط العرض/خط الطول. يتم التعبير عن ذلك كزوج من الأرقام المضاعفة لتمثيل درجات خط العرض ودرجات خط الطول. ما لم يُحدّد خلاف ذلك، يجب أن يتوافق هذا العنصر مع معيار WGS84. يجب أن تكون القيم ضمن النطاقات العادية.

تمثيل JSON 
{
  "latitude": number,
  "longitude": number
}
الحقول
latitude

number

تمثّل هذه السمة خط العرض بالدرجات. يجب أن يكون ضمن النطاق [-90.0, +90.0].
longitude

number

تمثّل هذه السمة خط الطول بالدرجات. يجب أن تكون القيمة ضمن النطاق [-180.0, +180.0].

النتيجة

كيان واحد تمّت تسويته من طلب بحث عن موقع جغرافي معيّن، بالإضافة إلى مستوى الثقة في التسوية

تمثيل JSON 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
الحقول
entity

object (Entity)

النتائج فقط. الكيان الذي تمّت تسويته من طلب البحث عن الموقع الجغرافي
confidence

enum (Confidence)

النتائج فقط. مستوى الثقة في الحلّ.

الثقة

مستوى الثقة في الحلّ.

عمليات التعداد
CONFIDENCE_UNSPECIFIED القيمة التلقائية هذه القيمة غير مستخدَمة.
MEDIUM تشير الثقة المتوسطة إلى أنّ الحلّ من المرجّح أن يكون صحيحًا، ولكن قد تكون هناك حلول أخرى.
HIGH تشير الثقة العالية إلى أنّ عملية تحديد الموقع الجغرافي صحيحة وتمثّل كيانًا جغرافيًا مكانيًا معيّنًا (مثل مكان معيّن).