Skip to content

afm_tile.md

Latest commit

 

History

History
242 lines (185 loc) · 6.54 KB

afm_tile.md

File metadata and controls

242 lines (185 loc) · 6.54 KB

AFM Tile API

Use the AFM Tile API to retrieve web map tiles using the XYZ tile protocol

CiboLabs's National Comparison app demonstrates what is possible with the AFM Tile API.

See our online AFM Tile API docs for the list of endpoints.

Note: The older https://tiles.national.cibolabs.com/ end URL is still available but will be retired soon in favour of the newer https://tiles.afm.cibolabs.com. Existing code should be updated.

Examples

These examples use the curl program in a Linux terminal to send requests to the API. They assume:

  • you have curl installed
  • you have exchanged your credentials for an access token (see the Quickstart for how to do this). The access token is stored in the TOKEN variable

The AFM Tile API endpoints return image tiles in the PNG file format. Below, we demonstrate the mechanics of making HTTP requests for tiles. However, the returned PNGs may be of little practical use outside of a web mapping application.

Although it uses the Pasture Key Tile API, our demo Pasture Key app shows how to display tiles in a web mapping application. The same approach can be used to build a web mapping application using the tiles returned from the AFM Tile API.

/getimagedates

Note: /getimagedates is a method of the AFM API. It returns a list of dates for which the AFM has image data available. Use one of these dates when calling the AFM Tile API.

See /getimagedates for details.

/tsdm

Get a Total Standing Dry Matter (TSDM) web map tile for 21 August 2025 at zoom level 7 and tile grid X=115, Y=74.

GET https://tiles.afm.cibolabs.com/tsdm/20250821/7/115/74

curl -X GET \
    --output "tsdm_20250821_7_115_74.png" \
    -H "Authorization: Bearer ${TOKEN}" \
    -H "Accept: image/png" \
    "https://tiles.afm.cibolabs.com/tsdm/20250821/7/115/74"

/percentiletsdm

Get an image tile of the TSDM decile. Each pixel is coloured according to its decile rank (compared to a reference dataset) of Total Standing Dry Matter (TSDM).

GET https://tiles.afm.cibolabs.com/percentiletsdm/20250821/7/115/74

curl -X GET \
    --output "percentiletsdm_20250821_7_115_74.png" \
    -H "Authorization: Bearer ${TOKEN}" \
    -H "Accept: image/png" \
    "https://tiles.afm.cibolabs.com/percentiletsdm/20250821/7/115/74"

/fractionalcover

Get an image tile of fractional cover. Each pixel is coloured according to the proportions of these three fractions:

  • red: fraction of bare ground
  • green: fraction of green vegetation cover
  • blue: fraction of dead vegetation cover

GET https://tiles.afm.cibolabs.com/fractionalcover/20250821/7/115/74

curl -X GET \
    --output "fractionalcover_20250821_7_115_74.png" \
    -H "Authorization: Bearer ${TOKEN}" \
    -H "Accept: image/png" \
    "https://tiles.afm.cibolabs.com/fractionalcover/20250821/7/115/74"

/nbar

Get an image tile of image reflectance. NBAR is a technical term meaning nadir-view, BRDF-adjusted surface reflectance.

GET https://tiles.afm.cibolabs.com/nbar/20250821/7/115/74

curl -X GET \
    --output "nbar_20250821_7_115_74.png" \
    -H "Authorization: Bearer ${TOKEN}" \
    -H "Accept: image/png" \
    "https://tiles.afm.cibolabs.com/nbar/20250821/7/115/74"

/woodychange

Get an image of woody change. This is a thematic image where each class relates to a different kind of woody change. See the response from the /legend endpoint for woodychange for information on which numbers relate to what woody change type and the colours to be used.

Note that the first path parameter is a year. Valid years can be retrieved using the /woodychangeyears endpoint (below).

GET https://tiles.afm.cibolabs.com/woodychange/2022/11/1879/1193

curl -X GET \
    --output "woody_change_2022_11_1879_1193.png" \
    -H "Authorization: Bearer ${TOKEN}" \
    -H "Accept: image/png" \
    "https://tiles.afm.cibolabs.com/woodychange/2022/11/1879/1193"

/woodychangeyears

Get a list of valid years that can be used with the /woodychange endpoint

GET https://tiles.afm.cibolabs.com/woodychangeyears

curl -X GET \
    --output "woody_change_years.json" \
    -H "Authorization: Bearer ${TOKEN}" \
    -H "Accept: application/json" \
    "https://tiles.afm.cibolabs.com/woodychangeyears"

/groundcover

Get an estimate of percentage ground cover for a season. The season is specified by the "yearmonth" (year + month) of the end of the season. The list of available yearmonths can be retrieved by calling /groundcoveryearmonths (below)

GET https://tiles.afm.cibolabs.com/groundcover/209405/1879/1193

curl -X GET \
    --output "woody_change_2022_11_1879_1193.png" \
    -H "Authorization: Bearer ${TOKEN}" \
    -H "Accept: image/png" \
    "https://tiles.afm.cibolabs.com/groundcover/209405/1879/1193"

/groundcoveryearmonths

Get a list of valid yearmonths that can be used with the /groundcover endpoint.

GET https://tiles.afm.cibolabs.com/groundcoveryearmonths

curl -X GET \
    --output "woody_change_years.json" \
    -H "Authorization: Bearer ${TOKEN}" \
    -H "Accept: application/json" \
    "https://tiles.afm.cibolabs.com/groundcoveryearmonths"

/legend

The pixels of the tiles are coloured. The colours represents a measurement range or category. For example, for the TSDM product, the pasture biomass of red pixels is less than 250 kg/ha.

Call the /legend endpoint to return a text version of the colour table.

Specify the name of the product as the first path parameter to this endpoint.

/legend does not support the fractionalcover product. Please contact us if you need a legend for fractional cover to display in your application.

Nor does /legend support the nbar product. No colour table is required because it is a reflectance image.

request

GET https://tiles.afm.cibolabs.com/legend/tsdm

curl -X GET \
    --output "tsdm_legend.json" \
    -H "Authorization: Bearer ${TOKEN}" \
    -H "Accept: application/json" \
    "https://tiles.afm.cibolabs.com/legend/tsdm"

response

tsdm_legend.json:

{
  "title": "Biomass (kg/ha)",
  "legend": [
    {
      "label": "<=250",
      "color": [
        215,
        25,
        28
      ]
    },
    {
      "label": "250 - 500",
      "color": [
        234,
        99,
        62
      ]
    },
    {
      "label": "500 - 750",
      "color": [
        253,
        174,
        97
      ]
    },
    ...
  ]
}