Method: forecast.lookup

可針對超過 65 個國家/地區傳回 5 天的每日花粉資訊,解析度最高可達 1 公里。

HTTP 要求

GET https://pollen.googleapis.com/v1/forecast:lookup

這個網址使用 gRPC 轉碼語法。

查詢參數

參數
location

object (LatLng)

必要欄位。API 搜尋花粉預報預報資料的經緯度。

days

integer

必要欄位。表示要請求的預測天數 (最小值 1,最大值為 5)。

pageSize

integer

選用設定。每頁傳回的每日資訊記錄數量上限。預設值為 5,表示 5 天的資料。

pageToken

string

選用設定。上一次每日呼叫所接收的網頁符記。系統會使用它來擷取後續網頁。

請注意,提供網頁符記的值時,您提供的所有其他請求參數都必須與先前提供網頁符記的呼叫相符。

languageCode

string

選用設定。允許用戶端選擇回應語言。如果無法提供該語言的資料,API 會使用最接近的項目。允許的值須符合 IETF BCP-47 標準。預設值為「en」(英文)。

plantsDescription

boolean

選用設定。包含植物的一般資訊,包括植物的一般資訊、特殊形狀和顏色、過敏的交叉反應資訊和植物相片。預設值為「true」。

要求主體

要求主體必須為空白。

回應主體

如果成功,回應主體即會包含具有以下結構的資料:

JSON 表示法
{
  "regionCode": string,
  "dailyInfo": [
    {
      object (DayInfo)
    }
  ],
  "nextPageToken": string
}
欄位
regionCode

string

與要求中提供的地點對應的國家/地區 ISO_3166-1 alpha-2 代碼。如果要求中提供的地點位於有爭議的地區,回應中可能會省略這個欄位。

dailyInfo[]

object (DayInfo)

必要欄位。這個物件包含每日要求每日的天氣預報資訊。

nextPageToken

string

選用設定。用於擷取下一頁的憑證。

授權範圍

需要下列 OAuth 範圍:

  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱 OAuth 2.0 總覽

LatLng

代表經緯度組合的物件。以一對雙精準數表示經度度數和緯度度數。除非另有指定,否則這個物件必須符合 WGS84 標準。此外,值必須在正規化範圍內。

JSON 表示法
{
  "latitude": number,
  "longitude": number
}
欄位
latitude

number

緯度度數,必須介於 [-90.0, +90.0] 的範圍之間。

longitude

number

經度度數,必須介於 [-180.0, +180.0] 的範圍之間。

DayInfo

這個物件包含每日要求每日的天氣預報資訊。

JSON 表示法
{
  "date": {
    object (Date)
  },
  "pollenTypeInfo": [
    {
      object (PollenTypeInfo)
    }
  ],
  "plantInfo": [
    {
      object (PlantInfo)
    }
  ]
}
欄位
date

object (Date)

花粉指數預測資料顯示的日期 (世界標準時間)。

pollenTypeInfo[]

object (PollenTypeInfo)

這份清單最多會列出三種花粉類型 (GRASS、WEED、TREE),會影響要求中指定的地點。

plantInfo[]

object (PlantInfo)

這份清單最多會列出 15 種花粉物種,影響了要求中指定的位置。

日期

代表完整或部分的日曆日期,例如生日。您可以指明時段和時區,或者在其他地方指定時間或時區。日期以公曆為基準。可能代表下列其中一項:

  • 完整日期,具有非零的年、月和日值。
  • 日期為 0 的月份和日期,例如週年紀念日。
  • 有 1 年,第 0 個月卻為 0 天。
  • 年和月,但數字為零 (例如信用卡到期日)。

相關類型:

JSON 表示法
{
  "year": integer,
  "month": integer,
  "day": integer
}
欄位
year

integer

日期的年份。這個值必須介於 1 至 9999,或 0 之間可指定不含年份的日期。

month

integer

一年中的月份。必須介於 1 到 12 之間,或 0 可以指定不含月份和日期的年份。

day

integer

一個月中的第幾天。這個值必須介於 1 至 31 之間,且有效的年份和月份;或 0 可讓您指定本身或年份和月份,但這些日期不明顯。

PollenTypeInfo

這個物件包含花粉類型索引和特定花粉類型健康建議資訊。

JSON 表示法
{
  "code": enum (PollenType),
  "displayName": string,
  "indexInfo": {
    object (IndexInfo)
  },
  "healthRecommendations": [
    string
  ],
  "inSeason": boolean
}
欄位
code

enum (PollenType)

花粉類型的代碼名稱。例如:「GRASS」

displayName

string

使用者容易理解的花粉類型名稱表示法。例如:「草」

indexInfo

object (IndexInfo)

包含花粉類型的通用汙染指數 (UPI) 資料。

healthRecommendations[]

string

說明文字清單,與目前花粉濃度相關的健康洞察資訊。

inSeason

boolean

用於表示植物是否屬於季節。

PollenType

花粉類型代碼

列舉
POLLEN_TYPE_UNSPECIFIED 未指定的植物類型。
GRASS 草皮花粉類型。
TREE 樹木花粉類型。
WEED 草粉類型。

IndexInfo

這個物件包含代表特定花粉指數值、類別和說明的資料。

JSON 表示法
{
  "code": enum (Index),
  "displayName": string,
  "category": string,
  "indexDescription": string,
  "color": {
    object (Color)
  },
  "value": integer
}
欄位
code

enum (Index)

索引的程式碼。這個欄位表示用於程式設計的索引,會使用蛇形案例而非空格。例如:「UPI」。

displayName

string

使用者可理解的索引名稱表示法。例如:「通用花粉指數」。

category

string

索引數值解釋的文字分類。索引包含六個類別:

  • 0:「無」
  • 1:「非常低」
  • 2: "低"
  • 3:「中度」
  • 4:「高」
  • 5: "非常高
indexDescription

string

目前索引等級的文字說明。

color

object (Color)

代表花粉指數數值分數的顏色。

value

integer

索引的數值分數。數字範圍介於 0 到 5 之間。

索引

索引代碼

列舉
INDEX_UNSPECIFIED 未指定的索引。
UPI 通用花粉指數

顏色

此屬性代表 RGBA 色域中的顏色。這種呈現方式是為了簡化與不同語言的色彩表示法之間相互轉換的設計。例如,您可以透過 Java 將這個表示法的欄位輕鬆提供給 java.awt.Color 的建構函式;此方法也能一併提供給 iOS 中 UIColor 的 +colorWithRed:green:blue:alpha 方法;而且只要稍加練習,就可以輕鬆使用 JavaScript 將 CSS rgba() 字串格式化。

本參考頁面沒有關於解讀 RGB 值的絕對色彩空間資訊,例如 sRGB、Adobe RGB、DCI-P3 和 BT.2020。根據預設,應用程式應採用 sRGB 色域。

除非另有說明,否則需要決定顏色相等、實作時,如果所有顏色的紅色、綠色、藍色和 Alpha 值各有落差,兩者最多可以有 1e-5

範例 (Java):

 import com.google.type.Color;

 // ...
 public static java.awt.Color fromProto(Color protocolor) {
   float alpha = protocolor.hasAlpha()
       ? protocolor.getAlpha().getValue()
       : 1.0;

   return new java.awt.Color(
       protocolor.getRed(),
       protocolor.getGreen(),
       protocolor.getBlue(),
       alpha);
 }

 public static Color toProto(java.awt.Color color) {
   float red = (float) color.getRed();
   float green = (float) color.getGreen();
   float blue = (float) color.getBlue();
   float denominator = 255.0;
   Color.Builder resultBuilder =
       Color
           .newBuilder()
           .setRed(red / denominator)
           .setGreen(green / denominator)
           .setBlue(blue / denominator);
   int alpha = color.getAlpha();
   if (alpha != 255) {
     result.setAlpha(
         FloatValue
             .newBuilder()
             .setValue(((float) alpha) / denominator)
             .build());
   }
   return resultBuilder.build();
 }
 // ...

範例 (iOS / Obj-C):

 // ...
 static UIColor* fromProto(Color* protocolor) {
    float red = [protocolor red];
    float green = [protocolor green];
    float blue = [protocolor blue];
    FloatValue* alpha_wrapper = [protocolor alpha];
    float alpha = 1.0;
    if (alpha_wrapper != nil) {
      alpha = [alpha_wrapper value];
    }
    return [UIColor colorWithRed:red green:green blue:blue alpha:alpha];
 }

 static Color* toProto(UIColor* color) {
     CGFloat red, green, blue, alpha;
     if (![color getRed:&red green:&green blue:&blue alpha:&alpha]) {
       return nil;
     }
     Color* result = [[Color alloc] init];
     [result setRed:red];
     [result setGreen:green];
     [result setBlue:blue];
     if (alpha <= 0.9999) {
       [result setAlpha:floatWrapperWithValue(alpha)];
     }
     [result autorelease];
     return result;
}
// ...

範例 (JavaScript):

// ...

var protoToCssColor = function(rgb_color) {
   var redFrac = rgb_color.red || 0.0;
   var greenFrac = rgb_color.green || 0.0;
   var blueFrac = rgb_color.blue || 0.0;
   var red = Math.floor(redFrac * 255);
   var green = Math.floor(greenFrac * 255);
   var blue = Math.floor(blueFrac * 255);

   if (!('alpha' in rgb_color)) {
      return rgbToCssColor(red, green, blue);
   }

   var alphaFrac = rgb_color.alpha.value || 0.0;
   var rgbParams = [red, green, blue].join(',');
   return ['rgba(', rgbParams, ',', alphaFrac, ')'].join('');
};

var rgbToCssColor = function(red, green, blue) {
  var rgbNumber = new Number((red << 16) | (green << 8) | blue);
  var hexString = rgbNumber.toString(16);
  var missingZeros = 6 - hexString.length;
  var resultBuilder = ['#'];
  for (var i = 0; i < missingZeros; i++) {
     resultBuilder.push('0');
  }
  resultBuilder.push(hexString);
  return resultBuilder.join('');
};

// ...
JSON 表示法
{
  "red": number,
  "green": number,
  "blue": number,
  "alpha": number
}
欄位
red

number

以間隔 [0, 1] 表示的值代表紅色的量。

green

number

間隔 [0, 1] 內色彩的綠色量。

blue

number

以色彩呈現的藍色量為間隔 [0, 1] 的值。

alpha

number

應套用至像素的色彩比例。也就是說,最終像素顏色會由這個方程式定義:

pixel color = alpha * (this color) + (1.0 - alpha) * (background color)

也就是說,值 1.0 對應單色,值 0.0 則對應完全透明的顏色。這會使用包裝函式訊息,而非簡單的浮點純量,因此能夠區分預設值和未設定的值。如果省略,此顏色物件會算繪為單色 (如同 Alpha 值已明確指定 1.0 值)。

PlantInfo

這個物件包含特定植物的每日資訊。

JSON 表示法
{
  "code": enum (Plant),
  "displayName": string,
  "indexInfo": {
    object (IndexInfo)
  },
  "plantDescription": {
    object (PlantDescription)
  },
  "inSeason": boolean
}
欄位
code

enum (Plant)

植物代碼名稱。例如「COTTONWOOD」。這裡列出了所有可用的代碼。

displayName

string

人類可讀的植物名稱表示法。例如:「楊木」。

indexInfo

object (IndexInfo)

這個物件包含代表特定花粉指數值、類別和說明的資料。

plantDescription

object (PlantDescription)

包含植物的一般資訊,包括植物的一般資訊、特殊形狀和顏色、過敏的交叉反應資訊和植物相片。

inSeason

boolean

表示植物與季節。

植物

列出不同地點供應情況的可用植物。

列舉
PLANT_UNSPECIFIED 未指定的植物代碼。
ALDER 阿爾德屬於樹狀花粉類型。
ASH 梣樹是一種樹花粉類型。
BIRCH 樺樹屬於樹花類型,
COTTONWOOD 楊木屬於樹木花粉類型。
ELM Elm 屬於樹狀花粉類型。
MAPLE Maple 分為樹木花粉類型。
OLIVE 橄欖屬於樹花類型。
JUNIPER 刺柏屬於樹狀花粉類型。
OAK 橡樹屬於樹花類型。
PINE 松樹屬於樹花類型,
CYPRESS_PINE 柏松樹屬於樹木花粉類型。
HAZEL 霧灰色屬於樹木花粉類型。
GRAMINALES 文法類屬植物的花粉類型。
RAGWEED 豚草屬於雜草類。
MUGWORT 艾草屬於雜草類花粉類型。

PlantDescription

包含植物的一般資訊,包括植物的一般資訊、特殊形狀和顏色、過敏的交叉反應資訊和植物相片。

JSON 表示法
{
  "type": enum (PollenType),
  "family": string,
  "season": string,
  "specialColors": string,
  "specialShapes": string,
  "crossReaction": string,
  "picture": string,
  "pictureCloseup": string
}
欄位
type

enum (PollenType)

植物的花粉類型。例如:「GRASS」。這裡列出了所有可用的代碼。

family

string

人類可讀的植物系列名稱。例如:「Betulaceae (樺樹家族)」。

season

string

花粉濃度季別說明的文字清單。範例:「冬季、春季」。

specialColors

string

植物的文字說明樹葉、樹皮、花朵或種子的色彩,有助於識別植物。

specialShapes

string

植物的文字說明樹葉、樹皮、花或種子有助於識別植物

crossReaction

string

花粉十字反應植物的文字說明。例:赤楊樹、榛樹、角樹、山毛櫸、柳樹和橡樹花粉。

picture

string

植物圖片的連結。

pictureCloseup

string

連結至植物的特寫圖片。