Data Point Definition¶
Gro defines a “data point” as a discrete result produced by our API. When using the get_data_points()
function, you are returned an array of points, each of which is a Python dictionary object that looks something like:
{ 'start_date': '2013-02-04T00:00:00.000Z',
'end_date': '2013-02-04T00:00:00.000Z',
'value': 0.131714797651,
'unit_id': 851,
'reporting_date': None,
'metadata': {},
'available_date': '2013-03-01T00:00:00.000Z',
'metric_id': 15531082,
'item_id': 7382,
'region_id': 138295,
'frequency_id': 1 }
For example, if you requested NDVI for Bureau county, Illinois, for a particular 8-day time period, the Gro API would yield a single response that would count as a single data point. Even though the value is computed from tens of thousands of underlying pixels, the API response counts as a single point because we are returning the value at the county (aka district) level.
Another example is if you get weekly precipitation data for a given region in a given week, you will get a single point. On the other hand, if you get daily precipitation for a given region for a period of a week, you will get seven data points.
Below are some explanations of what each of those fields represent:
start_date
: beginning of the period this point representsend_date
: end of the period this point representsvalue
: the value, typically a number. In some cases, the value may be non-numeric. E.g., when the metric is Crop Calendar, a value of “planting,” represents the fact that the planting period is fromstart_date
toend_date
.unit_id
: this is a Gro unit id you can look up the name/abbreviation/etc. of using theclient.lookup('units', unit_id)
function. There’s also a helper function of which you can see an example in the quickstart for getting just the abbreviation from the unit id,client.lookup_unit_abbreviation(point['unit_id'])
, which is the common case you probably wantmetadata
: additional information (i.e. {”conf_interval”: 0.7})reporting_date
: date when the source reported this value (None
if theshow_revisions
option wasn’t enabled, or if the source doesn’t provide a reporting date)available_date
: date when this value became stable in Gro’s system (included only if theshow_available_date
option is enabled)metric_id
: unique id for the metric (i.e. “Export Value (currency)”) you selected - get more details (name, definition, …) usingclient.lookup('metrics', metric_id)
item_id
: unique id for the item (i.e., “Corn”) you selected - get more details (name, definition, …) usingclient.lookup('items', item_id)
region_id
: unique id for the region (i.e., “United States”) you selected - get more details (name, administrative level, …) usingclient.lookup('regions', region_id)
frequency_id
: unique id for the frequency (i.e., “annual”) you selected - get more details (name, abbreviation, period length, …) usingclient.lookup('frequencies', frequency_id)