Pollen Observation

Edit online
The current US pollen observation content for a valid TWC location in the supported region or latitude/longitude. The US Pollen Observation returns the pollen observation content for a valid TWC located in the supported region or latitude/longitude coordinate. The API will return the index and index description for three pollen types (tree, weed, grass) and for mold. The API supports two languages – English and Spanish for the US.
Table of Contents

Audience

Geography

Background Technology

Response Format

Icon Codes, Weather Phrases and Images

Expiration

URL Construction

Overview

Understanding U.S. Pollen Observations

URL Format

Data Elements

Response Field Maintenance

Formatted Response Samples

Extensible Markup Language (XML) Example

JavaScript Object Notation (JSON) Example

Display Examples

Appendix

Pollen Types

Pollen Index Descriptions

Station Comments

Tree Names

Audience

This API is intended for web platforms.

Geography:U.S.A. Only

Background Technology: This API is a REST-based web service.

Response Format

This TWC API can return either JSON or XML formatted responses.

Icon Codes, Weather Phrases and Images

For the mapping of icon codes, weather phrases and images please refer to the Icon Code, Weather Phrases and Images document.

Translation: This TWC API handles the translation of phrases. However, when formatting a request URL a valid language must be passed along (see the language code table for the supported codes).

Fields Translated:

  • Tree names
  • Station Comments
  • Pollen Type
  • Pollen Description
  • HTTP Headers and Data Lifetime - Caching and Expiration

    For details on appropriate header values as well as caching and expiration definitions, please see The Weather Company Data | API Common Usage Guide.

    Expiration

    The response provides a data element expire_time_gmt. The value in this data element should be used to expire and remove a record from your system.

    URL Construction

    Please refer to the TWC API Common Usage document for a tutorial on URL construction and URL references.

Overview

The current US pollen observation content for a valid TWC location in the supported region or latitude/longitude. The US Pollen Observation returns the pollen observation content for a valid TWC located in the supported region or latitude/longitude coordinate. The API will return the index and index description for three pollen types (tree, weed, grass) and for mold. The API supports two languages – English and Spanish for the US.

Understanding U.S. Pollen Observations

Implementing the US Pollen Observations API requires your applications to perform basic processing in order to properly ingest this data.

U.S. Pollen Observations Composition

Pollen data provided through this API is sourced from trusted third-party organization that collects data from allergist’s offices on weekdays, Monday – Friday, except holidays. There are four segments of the data feed. The first contains the metadata, which includes the specified language parameter in the request URL. The US Pollen Observation content is presented in either English by default or translated into Spanish when the Spanish language parameter is used. The remaining data segments contain information on the location, reporting date/time and station, the specific tree species, and index for tree pollen, grass pollen, weed pollen, or mold count.

URL Format

Atomic API URL Examples:

Your content licensing agreement with TWC determines the number of days returned in the API response and is constrained by the API Key that is provided to your company.

  

Request by Geocode (Latitude & Longitude):

https://api.weather.com/v1/geocode/34.063/-84.217/observations/pollen.<json or xml>?language=en-US&apiKey=yourApiKey

Required Parameters:

geocode, language, format
https://api.weather.com/v1/geocode/34.063/-84.217/observations/pollen.json?language=en-US&apiKey=yourApiKey  

Request by Postal Code:

The Postal Code has a TWC proprietary location type (4) with the following format: location/<postal code>:<location type>:<country code>

https://api.weather.com/v1/location/30075:4:US/observations/pollen.<json or xml>?language=en-US&apiKey=yourApiKey

Required Parameters:

postal code:4:country code, language, format
https://api.weather.com/v1/location/30075:4:US/observations/pollen.json?language=en-US&apiKey=yourApiKey  

Data Elements

Data Element Rule Definitions

Each data element has three rules associated with it as defined below.

This Rule … … does this … … and answers this …
Usage Rule

Determines whether a data element is required or optional.

If it is optional, determines whether or not you can substitute it with a different data element.

 Must I use this data element or can I replace it with a different one?
Processing Rule Defines how to process a data element so the results are correct. If I use this data element, how do I process it?
Display Rule Defines the proper display format for a data element. How do I display this data element?

Data Element Descriptions

Outbound JSON/XML Description Type Length Range Null Sample Usage Processing Display
Metadata                  
version API version number String 4 N 1 required none   do not display
transaction_id Generated transaction id for the API call String varies N 7506556217027201134 required none   do not display
expire_time_gmt Data expiration date/ time in UNIX seconds Long 10 unlimited N 1373914800 required none do not display
US Pollen Observations                  
class type of data String 12 pollenobs N pollenobs required none do not display
loc_id pollen station id String 3 any valid pollen station N ATL required none do not display
loc_nm city name String 45 N Atlanta required none display as provided
loc_st state String 2 N GA required none   display as provided
rpt_dt the date and time the pollen observation was reported Date 24 YYYY-MM-DD'T'HH:MM:SSZ N 2014-04-08T15:00:00Z required none do not display
process_time_gmt processed date/time in UNIX seconds Long 10 unlimited N 1367892140 required none do not display
Tree Name – occurs 3 times                  
tree_nm the name of the tree species with the highest observed pollen count String 10 see Tree Names N Cedar optional none display as provided
total_pollen_cnt

the total observed pollen count of the specified plants being measured at

the location

 Integer 5 grains per cubic meter Y 551 grains per cubic meter optional none display as provided
stn_cmnt_cd the pollen station comment code String 1

A - No Report

B - Equipment Failure

C - Reports only during weed pollen season

D - Reports Suspended

E - Rain/Inclement Weather

F - Does not report year round

G - Report valid more than one day

H- Operating Normally

 Y H optional none do not display
stn_cmnt the reporting status of the pollen station String 50 see Station Comments Y operating normally optional none display as provided
Pollen Observation – Occurs 4 times – Tree, Grass, Weed and Mold                  
pollen_type type of pollen String 16 see Pollen Types N Tree required none display as provided
pollen_idx pollen index value String 1 0 to 4 or 9 N 1 required none display as provided
pollen_desc pollen index description String 12 see Pollen Index Descriptions N 1 required none display as provided

Response Field Maintenance

TWC strives to minimize the impact of changes in our weather content to your applications. TWC will not remove, rename or change the data type (int, string) of any data fields in the API response. However, TWC may add new data fields without notice.

Formatted Response Samples

Extensible Markup Language (XML) Example JavaScript Object Notation (JSON) Example

<response>

<script id="script_privacy"/>

<metadata>

<version>1</version>

<transaction_id>3024609351603579883</transaction_id>

<expire_time_gmt>1397271306</expire_time_gmt>

</metadata>

<pollenobservations>

<class>pollenobs</class>

<loc_id>ATL</loc_id>

<loc_nm>Atlanta</loc_nm>

<loc_st>GA</loc_st>

<rpt_dt>2014-04-08T15:00:00Z</rpt_dt>

<process_time_gmt>1396983306</process_time_gmt>

<treenames>

<tree_nm>Oak</tree_nm>

<tree_nm>Birch</tree_nm>

<tree_nm>Sweet Gum</tree_nm>

</treenames>

<total_pollen_cnt>1156</total_pollen_cnt>

<stn_cmnt_cd>H</stn_cmnt_cd>

<stn_cmnt>Operating Normally</stn_cmnt>

<pollenobservation>

<pollen_type>Tree</pollen_type>

<pollen_idx>4</pollen_idx>

<pollen_desc>Very High</pollen_desc>

</pollenobservation>

<pollenobservation>

<pollen_type>Grass</pollen_type>

<pollen_idx>0</pollen_idx>

<pollen_desc>None</pollen_desc>

</pollenobservation>

<pollenobservation>

<pollen_type>Weed</pollen_type>

<pollen_idx>0</pollen_idx>

<pollen_desc>None</pollen_desc>

</pollenobservation>

<pollenobservation>

<pollen_type>Mold</pollen_type>

<pollen_idx>9</pollen_idx>

<pollen_desc>No Data</pollen_desc>

</pollenobservation>

{"metadata":{

"language": "en-US",

"transaction_id": "1547239301440:523427864",

"version": "1",

"latitude": 32.73,

"longitude": -117.16,

"expire_time_gmt": 1547515441,

"status_code": 200

},

"pollenobservations":[

{"class":"pollenobs",

"loc_id":"ATL",

"loc_nm":"Atlanta",

"loc_st":"GA",

"rpt_dt":"2014-04-08T15:00:00Z",

"process_time_gmt":1396983306,

"treenames":[

{"tree_nm":"Oak"},

{"tree_nm":"Birch"},

{"tree_nm":"Sweet Gum"}

],

"total_pollen_cnt":1156,

"stn_cmnt_cd":"H",

"stn_cmnt":"Operating Normally",

"pollenobservation":[

{"pollen_type":"Tree","pollen_idx":"4","pollen_desc":"Very High"},

{"pollen_type":"Grass","pollen_idx":"0","pollen_desc":"None"},

{"pollen_type":"Weed","pollen_idx":"0","pollen_desc":"None"},

{"pollen_type":"Mold","pollen_idx":"9","pollen_desc":"No Data"}

]}]}

Display Examples

Pollen calendar

Appendix

Pollen Types
English Spanish
Grass Pasto
Weed Hierbas
Mold Moho
Tree Árbol
Pollen Index Descriptions
Index English Spanish
0 None Ninguno
1 Low Bajo
2 Moderate Moderado
3 High Elevado
4 Very High Fuerte
9 No Data Sin datos
Station Comments
English Spanish
No Report Sin informe
Equipment Failure Fallo del equipo
Reports only during weed pollen season Informes solo durante temporada de polen
Reports Suspended Informes suspendidos
Rain/Inclement Weather Lluvia/Tiempo severo
Does not report year round No informa el año entero
Report valid more than one day Informe valido por mas de un día.
Operating Normally Operando normalme
Tree Names
English Spanish
Alder Aliso
Ash Fresno
Aspen Álamo temblón
Birch Abedul
Cedar Cedro
Cottonwood Álamo de Virginia
Cypress Ciprés
Dogwood Cornejo
Elm Olmo
Hickory Nogal
Fir Abeto
Juniper Enebro
Maple Árbol de arce
Oak Roble
Olive Olivo
Pine Pino
Poplar Álamo
Redwood Secuoya
Sweet Gum Liquidámbar
Sycamore Sicomoro
Plum Ciruelo
Mulberry Morera
Beech Haya
Willow Sauce
Pecan Nogal de pecanas
No Report Sin informe