استخدام واجهة برمجة التطبيقات Region Lookup API مع "جداول بيانات Google"

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

يمكنك البحث عن أرقام تعريف الأماكن للمناطق بلا إنترنت من خلال استدعاء Region Lookup API من "جداول بيانات Google" باستخدام Apps Script. ننصح باستخدام هذه الطريقة لمجموعات البيانات التي تكون فيها معلَمات الإدخال غامضة ويمكن أن تؤدي إلى عدة معرّفات أماكن (مثل "10 شارع رئيسي")، ما قد يتطلّب تصحيح الأخطاء. تم توفير نموذج نص برمجي يتضمّن الوظائف التالية:

• يبحث SearchRegionByLocation عن مكان يتضمّن حدوده إحداثيات خطوط الطول والعرض المحدّدة.
• يبحث SearchRegionByAddress عن مكان يتضمّن حدوده العنوان المحدّد.
• SearchRegionByPlaceId للبحث عن مكان باستخدام معرّف المكان المحدّد.
• يبحث LookupRegionByName عن مكان بالاسم المحدّد.
• تبحث LookupRegionByUnitCode عن مكان باستخدام رمز الوحدة المحدّد.

تنبيه: إنّ Region Lookup API ورمز App Script هما إصداران تجريبيان.

الدوال المخصّصة الخاصة بميزة "البحث عن المنطقة"

لاستخدام الدوال المخصّصة، عليك أولاً إضافة رمز البرنامج النصي .gs الخاص بالدوال المخصّصة إلى محرّر البرامج النصية في "برمجة تطبيقات Google". بعد تحميل النص البرمجي، يمكنك استدعاء الدوال كما تستدعي أي دالة أخرى في جدول البيانات. تتلقّى البرامج النصية بيانات الإدخال من الخلايا. يمكنك استدعاء الدوال المخصّصة من جدول البيانات على النحو التالي: =LookupRegionByName(A2,C2,D2,E2)

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

معرّف المكان	‏‫عنوان URL لصفحة المكان‬	رمز الخطأ
ChIJLQQwv4qBb0gRIMaY1COLDQU	https://www.google.com/maps/search/?api=1&query=%20&query_place_id=ChIJLQQwv4qBb0gRIMaY1COLDQU

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

إضافة الدوال المخصّصة إلى "برمجة تطبيقات Google"

1. افتح جدول بيانات في "جداول بيانات Google".
2. اختَر عنصر القائمة الإضافات > برمجة التطبيقات.
3. احذف أي رمز في محرّر النصوص البرمجية.
4. انسخ الرمز من المثال أدناه والصقه في محرّر النصوص البرمجية.
5. استبدِل YOUR_API_KEY بمفتاح واجهة برمجة تطبيقات غير مقيّد يخص مشروعًا تم تفعيل واجهة برمجة التطبيقات الخاصة بالبحث عن المناطق فيه.
6. في أعلى الصفحة، انقر على "حفظ" .

/**
 * @fileoverview Provides custom Geo functions in Google Sheets for matching boundaries.
 * * SearchRegionByLocation searches for a region whose boundary contains the specified latitude/longitude coordinates.
 * * SearchRegionByAddress searches for a region whose boundary contains the specified address.
 * * SearchRegionByPlaceId searches for a region whose boundary contains the specified place ID.
 * * LookupRegionByName looks up a region with the specified name.
 * * LookupRegionByUnitCode looks up a region with the specified unit code.
 * @OnlyCurrentDoc
 */

var api_key = "YOUR_API_KEY"; // An unrestricted key is recommended for local use only (deployment is NOT recommended).

function format_url(place_id) {
  return place_id && 'https://www.google.com/maps/search/?api=1&query=%20&query_place_id=' + place_id;
}

function format_result(result) {
  let matches = result.matches || [];
  let firstMatch = result.matches[0] || {};

  let placeId = firstMatch.matchedPlaceId || '';
  let debugInfo = firstMatch.debugInfo || '';
  let candidates = firstMatch.candidatePlaceIds || [];

  return [[
    placeId || '(NULL)',
    format_url(placeId),
    debugInfo,
    candidates[0],
    format_url(candidates[0]),
    candidates[1],
    format_url(candidates[1]),
    candidates[2],
    format_url(candidates[2])
    ]];
}

/**
 * Searches for a place whose boundary contains the specified latitude/longitude coordinates.
 *
 * @param {number} latitude - The latitude where the place will be found (e.g., 37.531939).
 * @param {number} longitude - The longitude where the place will be found (e.g., -122.2994121).
 * @param {string} place_type - The place type of the place ("postal_code", "administrative_area_level_1", "administrative_area_level_2", "locality", or "country").
 *
 * @return {string} The place_id of the place, or null if none was found.
 *
 * @customfunction
 */
function SearchRegionByLocation(
  latitude, longitude, place_type) {
  var data = {
    "search_values": [ {
      "latlng": { 'latitude': latitude, 'longitude': longitude }, // { latitude: 37.531939, longitude: -122.2994121 }
      "place_type": place_type,
      "region_code": null,
      "language_code": null,
    } ]
  };

  var options = {
    'method' : 'post',
    'contentType': 'application/json',
    'headers': {
        'X-Goog-Api-Key' : api_key
      },
      // Convert the JavaScript object to a JSON string.
      'payload' : JSON.stringify(data)
    };

  var response = UrlFetchApp.fetch(
    'https://regionlookup.googleapis.com/v1alpha:searchRegion',
    options);

  var resultText = response.getContentText();
  console.log(resultText);
  var result = JSON.parse(resultText);

  return format_result(result);
}

/**
 * Searches for a place whose boundary contains the specified address.
 *
 * @param {string} address - An address within the place boundaries (e.g., "1505 Salado Dr, Mountain View, CA").
 * @param {string} place_type - The geo type id of the place (e.g., "locality").
 * @param {string} [region_code='us'] - The region code of the place (e.g., "US").
 * @param {string} [language_code='en'] - The language code of the place's name. (e.g., "en").
 *
 * @return {string} The place_id of the place, or null if none was found.
 *
 * @customfunction
 */

function SearchRegionByAddress(
  address, place_type, region_code, language_code) {

  var data = {
    "search_values": {
        "address": address,
        "place_type" : place_type,
        "region_code": region_code || 'us',
        "language_code": language_code || 'en',
      }
  };

  var options = {
    'method' : 'post',
    'contentType': 'application/json',
    'headers': {
        'X-Goog-Api-Key' : api_key
      },
      // Convert the JavaScript object to a JSON string.
      'payload' : JSON.stringify(data)
    };

  var response = UrlFetchApp.fetch(
    'https://regionlookup.googleapis.com/v1alpha:searchRegion',
    options);

  var resultText = response.getContentText();
  console.log(resultText);
  var result = JSON.parse(resultText);

  return format_result(result);
}


/**
 * Searches for a place with the specified place ID.
 *
 * @param {string} place_id - The place ID to search for.
 * @param {string} place_type - The geo type id of the place (e.g., "locality").
 * @param {string} [region_code='us'] - The region code of the place (e.g., "US").
 * @param {string} [language_code='en'] - The language code of the place's name. (e.g., "en").
 *
 * @return {string} The place_id of the place, or null if none was found.
 *
 * @customfunction
 */
function SearchRegionByPlaceId(
  place_id, place_type, region_code, language_code) {

 var data = {
   "search_values": {
       "place_id": place_id,
       "place_type" : place_type,
       "region_code": region_code || 'us',
       "language_code": language_code || 'en',
     }
 };

 var options = {
   'method' : 'post',
   'contentType': 'application/json',
   'headers': {
       'X-Goog-Api-Key' : api_key
     },
     // Convert the JavaScript object to a JSON string.
     'payload' : JSON.stringify(data)
   };

 var response = UrlFetchApp.fetch(
   'https://regionlookup.googleapis.com/v1alpha:searchRegion',
   options);
  var resultText = response.getContentText();
 console.log(resultText);
 var result = JSON.parse(resultText);

 return format_result(result);
}

/**
 * Looks up a place with the specified name.
 *
 * @param {string} place_name - The name of the place (e.g., "Palo Alto").
 * @param {string} place_type - The geo type id of the place (e.g., "locality").
 * @param {string} [region_code='us'] - The region code of the place (e.g., "US").
 * @param {string} [language_code='en'] - The language code of the place's name. (e.g., "en").
 *
 * @return {string} The place_id of the place, or null if none was found.
 *
 * @customfunction
 */
function LookupRegionByName(
  place, place_type, region_code, language_code) {
  var data = {
    "identifiers": [ {
        "place": '' + place,
        "place_type": place_type,
        "region_code": region_code || 'us',
        "language_code": language_code || 'en',
      }
    ]
  };

  var options = {
    'method' : 'post',
    'contentType': 'application/json',
    'headers': {
        'X-Goog-Api-Key' : api_key
      },
      // Convert the JavaScript object to a JSON string.
      'payload' : JSON.stringify(data),
      //'muteHttpExceptions' : true,
    };

  var response = UrlFetchApp.fetch(
    'https://regionlookup.googleapis.com/v1alpha:lookupRegion',
    options);

  var resultText = response.getContentText();

  console.log(resultText);
  var result = JSON.parse(resultText);

  return format_result(result);
}

/**
 * Looks up a place with the specified unit code.
 *
 * @param {string} place_name - The name of the place (e.g., "Palo Alto").
 * @param {string} place_type - The geo type id of the place (e.g., "locality").
 * @param {string} [region_code='us'] - The region code of the place (e.g., "US").
 * @param {string} [language_code='en'] - The language code of the place's name. (e.g., "en").
 *
 * @return {string} The place_id of the place, or null if none was found.
 *
 * @customfunction
 */
function LookupRegionByUnitCode(
  unit_code, place_type, region_code, language_code) {
  var data = {
    "identifiers": [ {
        "unit_code": '' + unit_code,
        "place_type": place_type,
        "region_code": region_code || 'us',
        "language_code": language_code || 'en',
      }
    ]
  };

  var options = {
    'method' : 'post',
    'contentType': 'application/json',
    'headers': {
        'X-Goog-Api-Key' : api_key
      },
      // Convert the JavaScript object to a JSON string.
      'payload' : JSON.stringify(data),
      //'muteHttpExceptions' : true,
    };

  var response = UrlFetchApp.fetch(
    'https://regionlookup.googleapis.com/v1alpha:lookupRegion',
    options);

  var resultText = response.getContentText();

  console.log(resultText);
  var result = JSON.parse(resultText);

  return format_result(result);
}