Gridded (Tiler) and Polygonal (Featurizer) Common Usage Guide

Overview

URL Construction

Using Tiler Info & Parameters

The Tiler Info API is used to retrieve current details about one or more products. By calling the v2/tiler/info API with the optional parameter ‘meta=true’, the details about each requested product’s native projection and valid Web Mercator tiles are delivered in the response.

• NOTE: All API requests for this endpoint are required to include the following header, prompting the system to compress the response: “Accept-Encoding: gzip”.

• The ‘products’ parameter can accept up to fifteen (15) comma-delimited values:

  • Example: products=1:Precipitationtypesurface,6:VAR01515FROM25011surface,19,20

  • Sample: https://api.weather.com/v2/tiler/info?products=1:Precipitationtypesurface,6:VAR01515FROM25011surface,19,20&apiKey=yourApiKey

• To retrieve the details on exactly one type of data from a product number, include the product number and the variable ID separated by a colon:

  • Example: products=300:tdprob

  • Sample: https://api.weather.com/v2/tiler/info?products=300:tdprob&apiKey=yourApiKey

• To retrieve the details on all data associated with a product number, include this number while omitting any variable IDs:

  • Example: products=300

  • Sample: https://api.weather.com/v2/tiler/info?products=300&apiKey=yourApiKey

Using Tiler Data & Parameters

The Tiler Data API retrieves tiles of meteorological data from one or more products.

• NOTE: All API requests for this endpoint are required to include the following header, prompting the system to compress the response: “Accept-Encoding: gzip”.

• products: the ‘products’ parameter for this endpoint must include both the product number and the variable ID, separated by a colon:

  • Example: products=300:PrecipIntensity

  • Sample: https://api.weather.com/v2/tiler/data?products=300:PrecipIntensity&t=1451606400000&lod=4&x=4&y=6&apiKey=yourApiKey

• dimension: the dimensions vary by API product, and valid dimensions can be found by calling /tiler/info

• lod, x, y: the combination of these tile parameters must correspond to a tile within the product’s tileset, found by calling /tiler/info?meta=true

• For the product’s native resolution, set lod to -1, and for the Web Mercator projection, use any valid lod value where lod ≥ 0

Using Tiler Byte & Parameters

The Tiler Byte API retrieves a byteset object that contains information regarding the values contained in each tile at all levels of detail for a single time value. Data includes minimum value and maximum value for the tile and whether there are empty cells (NaN values) in the tile.

• NOTE: All API requests for this endpoint are required to include the following header, prompting the system to compress the response: “Accept-Encoding: gzip”.

• products: the ‘products’ parameter for this endpoint must include both the product number and the variable ID, separated by a colon:

  • Example: products=300:PrecipIntensity

  • Sample: https://api.weather.com/v2/tiler/byte?products=300:PrecipIntensity&t=1451606400000&raw=false&apiKey=yourApiKey

• dimension: the dimensions vary by API product, and valid dimensions can be found by calling /tiler/info

• If raw is true, then the native layer byteset is returned. If raw is not given or is false, then the Web Mercator byteset for the pyramid is returned.

The entire pyramid (all LODs) of the tiles is returned concatenated in ascending raster-order (i.e. info for lod=0,x=0,y=0 (0,0,0) followed by lod=1,x=0,y=0 (1,0,0), (1,0,1), (1,1,0), (1,1,1), (2,0,0) and so on. Each tile is described by a record of up to 3 floating point values. If the first 4 bytes make up a floating point value of not-a-number, then the record is only 4 bytes long and the tile has no data. Calling Tiler API for such tiles should result in a 400 response. If the first 4 bytes do not make up a not-a-number value, then the record is 9 bytes long and should be decoded as follows.

1. The first 4 bytes make up the floating point value for the minimum value in the tile.

2. The second 4 bytes make up a floating point value that is the maximum value in the tile.

3. The last byte is a boolean that describes if any cells in the tile are empty, that is, the cell value is not-a-number.

Using Tiler Coverage & Parameters

The Tiler Coverage API retrieves a bitset object that contains a single bit for each tile at all levels of detail for a single time value. This bit flag denotes whether the given tile exists at that LOD and x, y.

• NOTE: All API requests for this endpoint are required to include the following header, prompting the system to compress the response: “Accept-Encoding: gzip”.

• products: the ‘products’ parameter for this endpoint must include both the product number and the variable ID, separated by a colon:

  • Example: products=300:PrecipIntensity

  • Sample: https://api.weather.com/v2/tiler/coverage?products=300:PrecipIntensity&t=1451606400000&apiKey=yourApiKey

• dimension: the dimensions vary by API product, and valid dimensions can be found by calling /tiler/info

• If raw is true, then the native layer bitset is returned. If raw is not given or is false, then the Web Mercator bitset for the pyramid is returned. Note that coverage data is typically not produced for the native layer. The API allows such requests, but a response will often be an error.

Using Tiler Extras Data & Parameters

The Tiler Extras Data API returns the same data as the /tiler/data call discussed above except that it allows the user to choose to receive data only over the oceans or only over land. This API may also be used to provide interpolated tile data at LODs otherwise not supported for a given product. See “Geographic Coverage” for more information on LODs available.

• NOTE: All API requests for this endpoint are required to include the following header, prompting the system to compress the response: “Accept-Encoding: gzip”.

• products: the ‘products’ parameter for this endpoint must include both the product number and the variable ID, separated by a colon:

  • Example: products=300:PrecipIntensity

  • Sample: https://api.weather.com/v2/tiler/extras/data?products=300:PrecipIntensity&stencil=true&interpolation=bicubic&t=1451606400000&lod=4&x=4&y=6&apiKey=yourApiKey

• dimension: the dimensions vary by API product, and valid dimensions can be found by calling /tiler/info

• lod, x, y: the combination of these tile parameters must correspond to a tile within the product’s tileset, found by calling /tiler/info?meta=true

• Optional Parameters: stencil, interpolation

• This API should only be used for the Web Mercator projection, i.e. lod value ≥ 0

Using Featurizer Tile & Parameters

The Featurizer Tile API retrieves a polygon or line tracing a particular threshold for a product’s data, for a single tile in Web Mercator projection.

• NOTE: All API requests for the first endpoint are required to include the following header, prompting the system to compress the response: “Accept-Encoding: gzip”.

• product: the ‘product’ parameter must include both the product number and the variable ID, separated by a colon:

  • Example: product=300:PrecipIntensity

  • Sample: https://api.weather.com/v2/featurizer/tile?product=300:PrecipIntensity&t=1451606400000&lod=4&x=4&y=6&apiKey=yourApiKey

• <dimensions>: dimensions vary by API product, and valid dimensions can be found by calling /tiler/info

• lod, x, y: the combination of these tile parameters must correspond to a tile within the product’s tileset, found by calling /tiler/info?meta=true

• The lod parameter must indicate the Web Mercator projection, where lod ≥ 0

  • To request the product’s native resolution, use the featurizer/feature endpoints

• Optional Parameters: operation, threshold, replacement, geometryType, crs, bbox

The API returns a geographic feature, namely a polygon or line as defined by the geometryType parameter. The API examines each pixel in the requested tile against the operation and threshold values, and the resulting feature corresponds to the area where the comparison evaluates to “true.”

The type of the response depends on the specific endpoint that is called, as documented below.

REQUIRED: All API responses must be compressed. The kmz, XZipped shp, and mvt file formats are compressed by definition; API requests for JSON objects, GeoJSON objects, and arrays of primitive data types must include the following HTTP header: “Accept-Encoding: gzip".

Using Featurizer Feature & Parameters

The Featurizer Feature API retrieves a polygon or line tracing a particular threshold for a product’s data, for all data in the product’s native projection.

• products: for this endpoint, this parameter must include both the product number and the variable ID, separated by a colon:

  • Example: products=300:PrecipIntensity

  • Sample: https://api.weather.com/v2/featurizer/feature?product=300:PrecipIntensity&t=1451606400000&apiKey=yourApiKey

• <dimensions>: dimensions vary by API product, and valid dimensions can be found by calling /tiler/info

• Optional Parameters: operation, threshold, replacement, geometryType, crs, bbox

The API returns a geographic feature, namely a polygon or line as defined by the geometryType parameter. The API examines each pixel in the product’s native projection against the operation and threshold values, and the resulting feature corresponds to the area where the comparison evaluates to “true.”

The type of the response depends on the specific endpoint that is called, as documented below.

REQUIRED: All API responses must be compressed. The .kmz, XZipped.shp, and .mvt file formats are compressed by definition; API requests for JSON objects, GeoJSON objects, and arrays of primitive data types must include the following HTTP header: “Accept-Encoding: gzip".

Using Featurizer Isoband & Parameters

The Featurizer Isoband API retrieves polygons containing all data between a lower and upper threshold, for all data in the product’s native projection.

• NOTE: All API requests for the first endpoint are required to include the following header, prompting the system to compress the response: “Accept-Encoding: gzip”.

• product: the ‘product’ parameter must include both the product number and the variable ID, separated by a colon:

  • Example: product=6:VAR01515FROM25011surface

  • Sample: https://api.weather.com/v2/featurizer/isoband?product=6:VAR01515FROM25011surface&threshold=35.0:40.0&t=1451606400000&apiKey=yourApiKey

• <dimensions>: dimensions vary by API product, and valid dimensions can be found by calling /tiler/info

• threshold: this should be two floating point values for lower and upper bounds, separated by a colon, e.g. threshold=35.0:40.0

• Optional Parameters: replacement, crs, bbox, format

• Unsupported parameters: lod, x, y

Query Parameter Elements & Definitions

Examples Using Select Parameters for Featurizer

For sample request: https://api.weather.com/v2/featurizer/tile?product=34:VAR0191200FROM25501heightaboveground&t=1451606400000&lod=4&x=4&y=6

&operation=greaterThanOrEqual&threshold=6.0&replacement=3.0&geometryType=polygon&apiKey=yourApiKey

Data Elements & Definitions

Note: The table below does not necessarily represent the sort order of the API response.

Appendix: Tiler Info meta=true

By calling the v2/tiler/info API with the optional parameter ‘meta=true’, the details about each requested products native projection and valid Web Mercator tiles are delivered in the response.

Appendix: Geographical Coverage

Data Tiles - Native Resolution, and Web Mercator Projection:

Each product used by Tiler and Featurizer uses data that was originally received in a native projection and then converted into the Web Mercator projection. Users can typically retrieve data and in either projection. There are more details on the lod parameter and the related parameters x and y in the section on API String Parameters, each projection and each level of detail value is summarized in the table below.

• The /tiler/data endpoint, the query string parameters lod, x, and y are used to retrieve individual tiles in both projections.

• The /featurizer/tile endpoints, the query string parameters lod, x, and y are used to retrieve geographic features for individual tiles only in the Web Mercator projection.

• The /featurizer/feature set of endpoints produce geographic features for all data in the native projection, without partitioning the data into tiles.

Appendix: Global Radar Tiles

For some sets of radar products, data is partitioned into Global Radar Tiles, where eight adjacent tiles of roughly equal size provide combined coverage for the entire globe. Two of these tiles span the International Date Line, so the data for each of these tiles is partitioned into two products to eliminate any possible ambiguity about the data’s time and date. The following table summarizes the approximate coverage for the Global Radar Tiles, including the split tiles that span the International Date Line. Ranges run west to east and north to south.

Appendix: Global Satellite Tiles

For some sets of satellite products, data is provided in Global Satellite Tiles, where ten adjacent tiles of various sizes provide coverage for the entire globe between 67°N to 67°S. The following table summarizes the approximate coverage for the Global Satellite Tiles, including the split tiles that span the International Date Line. Ranges run west to east and north to south.

Appendix: Aggregation

This endpoint returns up to four aggregated tiles. Subsequent tiles are requested by appending comma separated arguments to query arguments. The number of comma separated arguments to each query argument must be equal or the request is invalid. The aggregate tile response is composed of one flag float value optionally followed by a 256x256 float length tile. If the flag float value is 0x00000000 then no tile exists for the combination of comma separated arguments given, and therefore no tile data follows the flag. If the value of negative infinity is given, then a tile follows the flag.

• For example, /tiler/data-aggregate?products={pn1:vid1},{pn2:vid2},{pn:vid3},{pn4:vid4}&t={t1},{t2},{t3},{t4}&lod={lod1},{lod2},{lod3},{lod4}&x={x1},{x2},{x3},{x4}&y={y1},{y2},{y3},{y4}

  • Here, pn is the product number, vid is the variable ID, and t is the “t” (time) dimension; lod, x, and y are the tile coordinates

• Because the order is mandatory, the user should only aggregate products that use the same dimensions.

  • The user could aggregate observation products that all use just the t dimension.

  • The user could aggregate forecast products that all use t and rt dimensions.

  • The user should not aggregate a combination of the two types of products.

Examples

Adjacent tiles for the same product:

• https://api.weather.com/v2/tiler/data-aggregate?products=300:PrecipIntensity,300:PrecipIntensity&t=1451606400000,1451606400000&lod=4,4&x=3,4&y=6,6&apiKey=yourApiKey

Identical tiles for different products:

• https://api.weather.com/v2/tiler/data-aggregate?products=77:GOESNA1kmVSIRTOAV2,78:GOESNA4kmIR108TOAV2&t=1451606400000,1451606400000&lod=4,4&x=4,4&y=6,6&apiKey=yourApiKey

Response

The API returns a binary file with the MIME Content-Type “application/octet-stream”, compressed in response to the following mandatory header in the request: “Accept-Encoding: gzip”.

• The response is a gzipped float array, where there are 4 bytes per float in BIG_ENDIAN order.

• The results within the response will be ordered to match the comma-delimited list in the request’s parameters.

For each requested tile, the API returns one of the following.

Examples

• Two tiles requested, both tiles are successfully returned: 524,296 bytes in the response

  • Tile 1: 4-byte float of -Infinity followed by 262,144 bytes of data

  • Tile 2: 4-byte float of -Infinity followed by 262,144 bytes of data

• Two tiles requested, first tile is missing: 262,152 bytes in the response

  • Tile 1: 4-byte float with the value 0x00000000

  • Tile 2: 4-byte float of -Infinity followed by 262,144 bytes of data

• Two tiles requested, both tiles are missing: 8 bytes in the response

  • Tile 1: 4-byte float with the value 0x00000000

  • Tile 2: 4-byte float with the value 0x00000000