از منطقه جستجوی API با Google Sheets استفاده کنید

شما می‌توانید با فراخوانی API جستجوی منطقه از Google Sheets با استفاده از Apps Script، شناسه‌های مکان را برای مناطق به صورت آفلاین جستجو کنید. این روش برای مجموعه داده‌هایی که پارامترهای ورودی مبهم هستند و می‌توانند به چندین شناسه مکان (مثلاً "خیابان اصلی شماره ۱۰") تبدیل شوند، توصیه می‌شود، که ممکن است نیاز به اشکال‌زدایی داشته باشد. یک اسکریپت نمونه با توابع زیر ارائه شده است:

  • SearchRegionByLocation مکانی را جستجو می‌کند که مرز آن شامل مختصات طول/عرض جغرافیایی مشخص شده باشد.
  • SearchRegionByAddress مکانی را جستجو می‌کند که مرز آن شامل آدرس مشخص شده باشد.
  • SearchRegionByPlaceId به دنبال مکانی با شناسه مکان مشخص شده می‌گردد.
  • LookupRegionByName مکانی را با نام مشخص شده جستجو می‌کند.
  • LookupRegionByUnitCode مکانی را با کد واحد مشخص شده جستجو می‌کند.

توابع سفارشی جستجوی منطقه

برای استفاده از توابع سفارشی، ابتدا باید کد اسکریپت توابع سفارشی .gs را به ویرایشگر اسکریپت Apps Script اضافه کنید. پس از بارگذاری اسکریپت، می‌توانید توابع را مانند هر تابع صفحه گسترده دیگری فراخوانی کنید. اسکریپت‌ها داده‌های ورودی را از سلول‌ها دریافت می‌کنند. توابع سفارشی را از صفحه به این صورت فراخوانی کنید: =LookupRegionByName(A2,C2,D2,E2)

نتایج در سلولی که تابع در آن قرار دارد و دو سلول سمت راست نمایش داده می‌شوند. اگر شناسه‌های مکان کاندید موجود باشند، نتایج مربوط به آن شناسه‌های مکان نیز در سلول‌های مجاور نمایش داده می‌شوند. برای تأیید، پیوندی به صفحه مکان که نام منطقه و چندضلعی را در نقشه‌های گوگل نشان می‌دهد، ارائه شده است. در مثال زیر، اگر تابع در سلول A1 قرار داده شود، نتایج مشابه این خواهد بود:

شناسه مکان آدرس صفحه را قرار دهید کد خطا
ChIJLQQwv4qBb0gRIMaY1COLDQU https://www.google.com/maps/search/?api=1&query=%20&query_place_id=ChIJLQQwv4qBb0gRIMaY1COLDQU

در مثال قبلی، درخواست با موفقیت انجام شد، بنابراین سلول خطا خالی است. برای خطاهایی که مانع از اجرای صحیح اسکریپت می‌شوند (مانند حذف یک کلید API معتبر)، خطا به عنوان یک توضیح برای سلول حاوی تابع نمایش داده می‌شود.

توابع سفارشی را به Apps Script اضافه کنید

  1. یک صفحه گسترده را در Google Sheets باز کنید.
  2. گزینه منو Extensions > Apps Script را انتخاب کنید.
  3. هر کدی را در ویرایشگر اسکریپت حذف کنید.
  4. کد مثال زیر را کپی کرده و در ویرایشگر اسکریپت جایگذاری کنید.
  5. YOUR_API_KEY با یک کلید API نامحدود متعلق به پروژه‌ای که API جستجوی منطقه در آن فعال است، جایگزین کنید.
  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);
}