שימוש ב-Region Lookup API עם Google Sheets

המוצר או התכונה האלה הם ניסיוניים (בגרסת טרום-GA). התמיכה במוצרים ובתכונות בגרסת טרום-GA עשויה להיות מוגבלת, ויכול להיות ששינויים במוצרים ובתכונות בגרסת טרום-GA לא יהיו תואמים לגרסאות אחרות של טרום-GA. השימוש במוצרים בגרסת טרום-GA כפוף לתנאים הספציפיים לשירות של הפלטפורמה של מפות Google. מידע נוסף זמין בקטע תיאורים של שלבי ההשקה.

אפשר לחפש מזהי מקומות לאזורים במצב אופליין על ידי קריאה ל-Region Lookup API מ-Google Sheets באמצעות Apps Script. מומלץ להשתמש באפשרות הזו במערכי נתונים שבהם פרמטרי הקלט לא ברורים ויכולים להפנות לכמה מזהי מקומות (לדוגמה, 'רחוב ראשי 10'), וייתכן שיהיה צורך בניפוי באגים. סיפקנו סקריפט לדוגמה עם הפונקציות הבאות:

• ‫SearchRegionByLocation מחפש מקום שהגבול שלו מכיל את הקואורדינטות של קו הרוחב וקו האורך שצוינו.
• ‫SearchRegionByAddress מחפש מקום שהגבול שלו מכיל את הכתובת שצוינה.
• ‫SearchRegionByPlaceId מחפש מקום עם מזהה המקום שצוין.
• ‫LookupRegionByName מחפש מקום עם השם שצוין.
• ‫LookupRegionByUnitCode מחפש מקום עם קוד היחידה שצוין.

שימו לב: ‏ Region Lookup API וקוד App Script הם גרסאות ניסיוניות.

פונקציות מותאמות אישית של חיפוש אזורים

כדי להשתמש בפונקציות המותאמות אישית, צריך קודם להוסיף את קוד הסקריפט .gs של הפונקציות המותאמות אישית לכלי לעריכת סקריפטים ב-Apps Script. אחרי שהסקריפט נטען, אפשר להפעיל את הפונקציות כמו שמפעילים כל פונקציה אחרת בגיליון אלקטרוני. הסקריפטים מקבלים נתוני קלט מתאים. כדי להפעיל פונקציות מותאמות אישית מתוך הגיליון, משתמשים בתחביר הבא: =LookupRegionByName(A2,C2,D2,E2)

התוצאות מוצגות בתא שמכיל את הפונקציה, ובשני התאים שמשמאל. אם יש מזהים של מקומות פוטנציאליים, התוצאות של המזהים האלה יוצגו גם בתאים סמוכים. לצורך אימות, מסופק קישור לדף המקום שבו מוצגים שם האזור והמצולע במפות Google. בדוגמה הבאה, אם הפונקציה הייתה מודבקת בתא A1, התוצאות היו נראות כך:

מזהה מקום	כתובת אתר של דף מקום	קוד שגיאה
ChIJLQQwv4qBb0gRIMaY1COLDQU	https://www.google.com/maps/search/?api=1&query=%20&query_place_id=ChIJLQQwv4qBb0gRIMaY1COLDQU

בדוגמה הקודמת, הבקשה הצליחה ולכן תא השגיאה ריק. אם יש שגיאות שמונעות מהסקריפט לפעול בצורה תקינה (למשל, אם לא צוין מפתח API תקין), השגיאה תופיע כהערה בתא שמכיל את הפונקציה.

הוספת הפונקציות המותאמות אישית ל-Apps Script

1. פותחים גיליון אלקטרוני ב-Google Sheets.
2. בוחרים באפשרות בתפריט תוספים > 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);
}