Skip to content

API Specification

eightysteele edited this page Jan 13, 2012 · 1 revision

formats

  • .csv
  • .json
  • ?datefmt=seconds

nodata

nodata could mean we couldn't estimate (i.e. too many clouds) or not forest
we might want to include a specific nodata code for these cases
that is, cloud means something very different than not forest

aggregates

  • iso code
  • gadm 1 code
  • gadm 2 code
  • countries
  • provinces (gadm 1)
  • subprovinces (gadm 2)
  • ranked for countries/provinces/subprovinces

restrictions

  • admin by date
  • admin by probability threshold
  • ranking by date
  • ranking by probability threshold
  • ranking to top N

keywords

  • /countries
  • /provinces
  • /subprovinces
  • /cleared
  • /dates
  • /previous
  • /confidence
  • /latest most recent
  • /all
  • /lat/lon
  • /date
  • /when
  • /iso
  • /gadm
  • /rank

additional fields

  • ?date
  • ?startdate
  • ?enddate
  • ?ll

Countries

defor aggregates for all countries, most recent period
/countries
/countries/latest
/countries?date=latest

defor aggregates for all countries, summing last six months
/countries/previous/months/6
/countries?months=6

defor aggregates for all countries, summing last three years
/countries/previous/years/3
/countries?years=3

defor aggregate, ranked for all countries
/countries/latest/ranked/
/countries?date=latest&ranked=true

defor aggregate, ranked for top 10 countries
/countries/latest/ranked/10
/countries?date=latest&ranked=10

defor aggregate, summed over specific date range
/countries/rank/10?startdate=2010-1-1&enddate=2011-1-1

defor aggregate, summing starting at specific date
/countries/rank/10?startdate=2010-1-1

defor aggregate timeseries, by country
/countries/dates/all
/countries?dates=all

defor aggregate timeseries, by country for a range
/countries/dates?=startdate=2010-1-1&enddate=2011-1-1

Specific countries

country aggregate by year
/{iso}/years

country aggregate by months
/{iso}/months

country aggregate for all periods
/{iso}/all

country aggregate for latest period
/{iso}/latest

country aggregate for specific date
/{iso}/dates?startdate=2010-1-1&enddate=2010-1-1

country aggregate for range of dates
/{iso}/dates?startdate=2010-1-1&enddate=2011-1-1

country aggregate starting with a date and ending now
/{iso}/dates?stardate=2010-1-1

Provinces

for provinces/subprovinces, we'll want to start from a specific country
then it's the same as for countries

all provinces for a country
/{iso}/provinces

worst-10 provinces for a country, summed starting 2010-1-1
/{iso}/provinces/latest/rank/10?startdate=2010-1-1

defor aggregate timeseries, by province for a date range
/{iso}/provinces/dates?=startdate=2010-1-1&enddate=2011-1-1

defor aggregate for provinces, summed over specific date range
/{iso}/provinces/rank/10?startdate=2010-1-1&enddate=2011-1-1

GADM

Do everything as above (e.g. dates, months, years, etc.) but use provinces and GADM ids
/provinces/{gadm id}/etc.
/subprovinces/{gadm id}/etc.

Get list of gadm options, explaining the following
/gadm

Get list of iso codes and names
/gadm/iso

Get list of province codes and names
/gadm/provinces

Get list of province codes and names for a country
/gadm/{iso}/provinces

Get list of subprovince codes and names
/gadm/subprovinces

Get list of subprovince codes/names for a country
/gadm/{iso}/subprovinces

Get list of subprovince codes/names for a province
/gadm/provinces/{province id}/subprovinces

Pixels

get most recent detections everywhere
returns lat,lon of detections
/cleared/latest

get defor true/false for a specific latlon
returns true/false/nodata
/cleared/{lat}/{lon}

get defor date detected; returns false if not cleared; returns nodata if no record
/cleared/when/{lat}/{lon}

get confidence/probability cleared as of now
/cleared/confidence/{lat}/{lon}
/cleared/confidence?ll={lat},{lon}

get confidence/probability for all periods
return full ts, date start/stop, tres, sres
/cleared/confidence/all/{lat}/{lon}
/cleared/confidence/all?ll={lat},{lon}

We could also tweak these queries to change the confidence level (default is 50%)

Clone this wiki locally