Skip to content

Latest commit

 

History

History
105 lines (84 loc) · 5.62 KB

api-usage.md

File metadata and controls

105 lines (84 loc) · 5.62 KB
Raw

Using the API to explore and access datasets

The production API is currently accessible at this URL: https://8ib71h0627.execute-api.us-east-1.amazonaws.com/v1/

API documentation can be found under https://8ib71h0627.execute-api.us-east-1.amazonaws.com/docs

Metadata and configuration information for all the datasets available in the dashboard can be found at the /datasets endpoint.

There are two categories of datasets: global, datasets that span the entire globe, and spotlight, datasets that only exist for certain spotlight cities/areas. The spotlight areas available and their metadata can be found at the /sites endpoint.

Appending a site id from the /sites endpoint to the /datasets endpoint will return all the datasets that are available for that spotlight (ie: /datasets/be will return all datasets available for the Beijing spotlight). The /datasets/global endpoint will return all of the global spotlights. Note that all global spotlights are also included in the datasets specific to a spotlight, since the data does exist for that spotlight.

Here is the metadata for one of the datasets (Nightlights-VIIRS) availabe in the Beijing spotlight (dataset metadata for all Beijing datasets can be found at the /datasets/be enpoint)


{
      "id": "nightlights-viirs",
      "name": "Nightlights VIIRS",
      "type": "raster-timeseries",
      "isPeriodic": true,
      "timeUnit": "day",
      "domain": [
        "2020-01-01T00:00:00Z",
        "2020-12-01T00:00:00Z"
      ],
      "source": {
        "type": "raster",
        "tiles": [
          "https://8ib71h0627.execute-api.us-east-1.amazonaws.com/v1/{z}/{x}/{y}@1x?url=s3://covid-eo-data/bm_500m_daily/VNP46A2_V011_be_{date}_cog.tif&resampling_method=nearest&bidx=1&rescale=0%2C100&color_map=viridis"
        ]
      },
      "backgroundSource": null,
      "exclusiveWith": [
        "agriculture",
        "no2",
        "co2-diff",
        "co2",
        "fb-population-density",
        "car-count",
        "nightlights-hd",
        "detection-multi",
        "water-chlorophyll",
        "water-spm",
        "detections-ship",
        "detections-plane",
        "detections-vehicles"
      ],
      "swatch": {
        "color": "#C0C0C0",
        "name": "Grey"
      },
      "compare": null,
      "legend": {
        "type": "gradient",
        "min": "less",
        "max": "more",
        "stops": [
          "#440357",
          "#3b508a",
          "#208f8c",
          "#5fc961",
          "#fde725"
        ]
      },
      "paint": null,
      "info": "Darker colors indicate fewer night lights and less activity. Lighter colors indicate more night lights and more activity. Check out the HD dataset to see a light-corrected version of this dataset."
    }

The dataset source tiles are under the key source.tiles. Items surrounded by curly braces { and } should be replaced with apropriate values.

The {x} and {y} values, in combination with the zoom level, {z}, identify the Slippy Map Tilename of the tile to fetch. (eg: a tile containing Los Angeles has /{z}/{x}/{y} values: 9/87/204).

{date} should be of the format YYYYMM, if the value of timeUnit is month , and YYYY_MM_DD, if the value of timeUnit is day.

Dates available for the dataset are given by the domain key. If the isPeriodic value is True, then domain will only contain 2 dates, the start and end date. Any date within that range will be valid (remember that dates can either be daily (YYYY_MM_DD) or monthly ( YYYYMM)). For example, a periodic, monthly dataset can be requested with 202001 as the {date} field, to get data for January 2020 and 202002 for February 2020).

The URL for requesting data from the nightlights-viirs data for Beijing, for xyz coordinates z=9, x=421, y=193 on January 1st, 2020 would look something like:

https://8ib71h0627.execute-api.us-east-1.amazonaws.com/v1/9/421/193@1x?url=s3://covid-eo-data/bm_500m_daily/VNP46A2_V011_be_2020_01_01_cog.tif&resampling_method=nearest&bidx=1&rescale=0%2C100&color_map=viridis

Which will display in the browser.

You can also download the above tile with a curl command:

curl 'https://8ib71h0627.execute-api.us-east-1.amazonaws.com/v1/9/421/193@1x?url=s3://covid-eo-data/bm_500m_daily/VNP46A2_V011_be_2020_01_01_cog.tif&resampling_method=nearest&bidx=1&rescale=0%2C100&color_map=viridis' -o tile.tif

The source COGs, from which the API generates the tiles are publicly available at the location specified by the url parameter in the link above. For example, the source COG for the above tile can be downloaded using the aws-cli with the following command:

aws s3 cp s3://covid-eo-data/bm_500m_daily/VNP46A2_V011_be_2020_01_01_cog.tif ./cog.tif --no-sign-request

Some of the COGs can be quite large. To verify the size before downloading use this command:

aws s3 ls s3://covid-eo-data/bm_500m_daily/VNP46A2_V011_be_2020_01_01_cog.tif --summarize --human-readable --no-sign-request

# Output: 
2021-03-24 08:50:12    5.9 MiB VNP46A2_V011_be_2020_01_01_cog.tif

Total Objects: 1
   Total Size: 5.9 MiB