Gro API Client¶

api.client.lib¶

Base module for making API requests.

Client, GroClient, CropModel, and BatchClient all build on top of endpoints exposed in this module. Helper functions or shims or derivative functionality should appear in the client classes rather than here.

api.client.lib.format_crop_calendar_response(resp)[source]¶

Make cropcalendar output a format similar to get_data_points().

>>> format_crop_calendar_response([
...     {
...         'metricId': 2260063,
...         'itemId': 274,
...         'regionId': 13051,
...         'sourceId': 5,
...         'frequencyId': 15,
...         'data': [{
...             'sageItem': 'Corn',
...             'plantingStartDate': '2000-03-04',
...             'plantingEndDate': '2000-05-17',
...             'harvestingStartDate': '2000-07-20',
...             'harvestingEndDate': '2000-11-01',
...             'multiYear': False
...         }]
...     }
... ])
[{'metric_id': 2260063,
    'item_id': 274,
    'region_id': 13051,
    'frequency_id': 15,
    'source_id': 5,
    'start_date': '2000-03-04',
    'end_date': '2000-05-17',
    'value': 'planting',
    'input_unit_id': None,
    'input_unit_scale': None,
    'reporting_date': None},
    {'metric_id': 2260063,
    'item_id': 274,
    'region_id': 13051,
    'frequency_id': 15,
    'source_id': 5,
    'start_date': '2000-07-20',
    'end_date': '2000-11-01',
    'value': 'harvesting',
    'input_unit_id': None,
    'input_unit_scale': None,
    'reporting_date': None}]

Parameters:	resp (list of dicts) – The output from /v2/cropcalendar/data. See doctest
Returns:	points – The input resp dicts with keys modified to match the get_data_points output keys. Splits each point with plantingStartDate, plantingEndDate, harvestingStartDate, and harvestingEndDate into two points with start and end date where the value is the state of the crop as a string.
Return type:	list of dicts

api.client.lib.get_access_token(api_host, user_email, user_password, logger=None)[source]¶

Request an access token.

Parameters:	api_host (string) – The API host’s url, excluding ‘https://’ ex. ‘api.gro-intelligence.com’ user_email (string) – Email address associated with user’s Gro account user_password (string) – Password for user’s Gro account logger (logging.Logger) – Alternative logger object if wanting to use a non-default one. Otherwise get_default_logger() will be used.
Returns:	accessToken
Return type:	string

api.client.lib.get_available(access_token, api_host, entity_type)[source]¶

List the first 5000 available entities of the given type.

Parameters:

access_token (string) –
api_host (string) –
entity_type (string) – ‘items’, ‘metrics’, or ‘regions’

Returns:

data –

ex: [: { ‘id’: 0, ‘contains’: [1, 2, 3], ‘name’: ‘World’, ‘level’: 1}, { ‘id’: 1, ‘contains’: [4, 5, 6], ‘name’: ‘Asia’, ‘level’: 2}, …

]

Return type:

list of dicts

api.client.lib.get_crop_calendar_data_points(access_token, api_host, **selection)[source]¶

Get crop calendar data.

Has different input/output from the regular /v2/data call, so this normalizes the interface and output format to make compatible get_data_points().

Parameters:	access_token (string) – api_host (string) – selection (dict) – See get_crop_calendar_params() input
Returns:	See format_crop_calendar_response() output
Return type:	list of dicts

api.client.lib.get_crop_calendar_params(**selection)[source]¶

Construct http request params from dict of entity selections.

For use with get_crop_calendar_data_points()

>>> get_crop_calendar_params(**{
...     'metric_id': 123,
...     'item_id': 456,
...     'region_id': 14
... })
{'itemId': 456, 'regionId': 14}

Parameters:	selection (dict) – Keys can include: ‘item_id’, ‘region_id’. Anything else will be ignored. Only region and item are required since metric/item/source/frequency all have default values and start/end date are not allowed inputs since crop calendars are static.
Returns:	selections with valid keys converted to camelcase and invalid ones filtered out
Return type:	dict

api.client.lib.get_data(url, headers, params=None, logger=None)[source]¶

General ‘make api request’ function.

Assigns headers and builds in retries and logging.

Parameters:	url (string) – headers (dict) – params (dict) – logger (logging.Logger) –
Returns:	data
Return type:	list or dict

api.client.lib.get_data_call_params(**selection)[source]¶

Construct http request params from dict of entity selections.

For use with get_data_points().

>>> get_data_call_params(**{
...     'metric_id': 123,
...     'start_date': '2012-01-01',
...     'unit_id': 14
... })
{'metricId': 123, 'startDate': '2012-01-01'}

Parameters:	selection (dict) – Keys can include: ‘metric_id’, ‘item_id’, ‘region_id’, ‘partner_region_id’, ‘source_id’, ‘frequency_id’, ‘start_date’, ‘end_date’, ‘show_revisions’, and ‘insert_null’. Anything else will be ignored.
Returns:	selections with valid keys converted to camelcase and invalid ones filtered out
Return type:	dict

api.client.lib.get_data_points(access_token, api_host, **selection)[source]¶

Get all the data points for a given selection.

https://github.com/gro-intelligence/api-client/wiki/Data-Point-Definition

Parameters:

access_token (string) –
api_host (string) –
selection (dict) – See get_data_call_params() input

Returns:

Ex: [ {: “start_date”: “2000-01-01T00:00:00.000Z”, “end_date”: “2000-12-31T00:00:00.000Z”, “value”: 251854000, “input_unit_id”: 14, “input_unit_scale”: 1, “metric_id”: 860032, “item_id”: 274, “region_id”: 1215, “frequency_id”: 9, “unit_id”: 14

}, …]

Return type:

list of dicts

api.client.lib.get_data_series(access_token, api_host, **selection)[source]¶

Get available data series for the given selections.

https://github.com/gro-intelligence/api-client/wiki/Data-Series-Definition

Parameters:

access_token (string) –
api_host (string) –
selection (dict) – See get_params_from_selection() for more information on selection formatting

Returns:

ex: [{ ‘metric_id’: 2020032, ‘metric_name’: ‘Seed Use’,: ’item_id’: 274, ‘item_name’: ‘Corn’, ‘region_id’: 1215, ‘region_name’: ‘United States’, ‘source_id’: 24, ‘source_name’: ‘USDA FEEDGRAINS’, ‘frequency_id’: 7, ‘start_date’: ‘1975-03-01T00:00:00.000Z’, ‘end_date’: ‘2018-05-31T00:00:00.000Z’

}, { … }, … ]

Return type:

list of dicts

api.client.lib.get_default_logger()[source]¶

Get a logging object using the default log level set in cfg.

https://docs.python.org/3/library/logging.html

Returns:	logger
Return type:	logging.Logger

api.client.lib.get_descendant_regions(access_token, api_host, region_id, descendant_level)[source]¶

Look up details of regions of the given level contained by a region.

Given any region by id, recursively get all the descendant regions that are of the specified level.

This takes advantage of the assumption that region graph is acyclic. This will only traverse ordered region levels (strictly increasing region level id) and thus skips non-administrative region levels.

Parameters:

access_token (string) –
api_host (string) –
region_id (integer) –
descendant_level (integer) – The region level of interest. See REGION_LEVELS constant.

Returns:

Ex: [{: ‘id’: 13100, ‘contains’: [139839, 139857, …], ‘name’: ‘Wisconsin’, ‘level’: 4
} , {: ‘id’: 13101, ‘contains’: [139891, 139890, …], ‘name’: ‘Wyoming’, ‘level’: 4

}, …] See output of lookup()

Return type:

list of dicts

api.client.lib.get_geo_centre(access_token, api_host, region_id)[source]¶

Given a region ID, return the geographic centre in degrees lat/lon.

Parameters:

access_token (string) –
api_host (string) –
region_id (integer) –

Returns:

Ex: [{ ‘centre’: [ 45.7228, -112.996 ],: ’regionId’: 1215, ‘regionName’: ‘United States’ }]

Return type:

list of dicts

api.client.lib.get_geojson(access_token, api_host, region_id)[source]¶

Given a region ID, return a geojson shape information

Parameters:

access_token (string) –
api_host (string) –
region_id (integer) –

Returns:

a geojson object e.g.
{ ‘type’ (‘GeometryCollection’,) –

‘geometries’: [{‘type’: ‘MultiPolygon’,

’coordinates’: [[[[-38.394, -4.225], …]]]}, …]}
or None if not found.

api.client.lib.get_params_from_selection(**selection)[source]¶

Construct http request params from dict of entity selections.

For use with get_data_series() and rank_series_by_source().

>>> get_params_from_selection(**{
...     'metric_id': 123,
...     'item_id': 456,
...     'unit_id': 14
... })
{'metricId': 123, 'itemId': 456}

Parameters:	selection (dict) – Keys can include: ‘metric_id’, ‘item_id’, ‘region_id’, ‘partner_region_id’, ‘source_id’, ‘frequency_id’. Anything else will be ignored.
Returns:	selections with valid keys converted to camelcase and invalid ones filtered out
Return type:	dict

api.client.lib.list_available(access_token, api_host, selected_entities)[source]¶

List available entities given some selected entities.

Given one or more selections, return entities combinations that have data for the given selections.

Parameters:

access_token (string) –
api_host (string) –
selected_entities (dict) – ex: { ‘metric_id’: 123, ‘item_id’: 456, ‘source_id’: 7 } Keys may include: metric_id, item_id, region_id, partner_region_id, source_id, frequency_id

Returns:

ex: [

{ ‘metric_id’: 11078, ‘metric_name’: ‘Export Value (currency)’,: ’item_id’: 274, ‘item_name’: ‘Corn’, ‘region_id’: 1215, ‘region_name’: ‘United States’, ‘source_id’: 15, ‘source_name’: ‘USDA GATS’ },

{ … }, …

]

Return type:

list of dicts

api.client.lib.lookup(access_token, api_host, entity_type, entity_id)[source]¶

Retrieve details about a given id of type entity_type.

https://github.com/gro-intelligence/api-client/wiki/Entities-Definition

Parameters:

access_token (string) –
api_host (string) –
entity_type (string) – ‘items’, ‘metrics’, ‘regions’, ‘units’, or ‘sources’
entity_id (int) –

Returns:

ex: {: ‘id’: 274, ‘contains’: [779, 780, …] ‘name’: ‘Corn’, ‘definition’: ‘The seeds of the widely cultivated corn plant

<i>Zea mays</i>, which is one of the world’s most popular grains.’

}

Return type:

dict

api.client.lib.lookup_belongs(access_token, api_host, entity_type, entity_id)[source]¶

Look up details of entities containing the given entity.

Parameters:

access_token (string) –
api_host (string) –
entity_type (string) – One of: ‘metrics’, ‘items’, ‘regions’, or ‘sources’
entity_id (integer) –

Yields:

dict – Result of lookup() on each entity the given entity belongs to. ex: For the region ‘United States’, one yielded result will be for ‘North America.’ The format of which matches the output of lookup(): {

‘id’: 15, ‘contains’: [ 1008, 1009, 1012, 1215, … ], ‘name’: ‘North America’, ‘level’: 2

}

api.client.lib.rank_series_by_source(access_token, api_host, series_list)[source]¶

Given a list of series, return them in source-ranked order.

If there are multiple sources for the same selection, the prefered source comes first. Differences other than source_id are not affected.

Parameters:	access_token (string) – api_host (api_host) – series_list (list of dicts) – See output of get_data_series()
Yields:	dict – The input series_list but reordered by source rank

api.client.lib.redirect(params, migration)[source]¶

Update query parameters to follow a redirection response from the API.

>>> redirect({'metricId': 14, 'sourceId': 2, 'itemId': 145},
...          {'old_metric_id': 14, 'new_metric_id': 15, 'source_id': 2})
{'metricId': 15, 'sourceId': 2, 'itemId': 145}

Parameters:	params (dict) – The original parameters provided to the API request migration (dict) – The body of the 301 response indicating which of the inputs have been migrated and what values they have been migrated to
Returns:	params – The mutated params object with values replaced according to the redirection instructions provided by the API
Return type:	dict

api.client.lib.search(access_token, api_host, entity_type, search_terms)[source]¶

Search for the given search term. Better matches appear first.

Parameters:	access_token (string) – api_host (string) – entity_type (string) – One of: ‘metrics’, ‘items’, ‘regions’, or ‘sources’ search_terms (string) –
Returns:	Ex: [{‘id’: 5604}, {‘id’: 10204}, {‘id’: 10210}, ….]
Return type:	list of dicts

api.client.lib.search_and_lookup(access_token, api_host, entity_type, search_terms)[source]¶

Search for the given search terms and look up their details.

For each result, yield a dict of the entity and it’s properties: { ‘id’: <integer id of entity, unique within this entity type>,

‘name’: <string canonical name> ‘contains’: <array of ids of entities that are contained in this one>, …. <other properties> }

Parameters:

access_token (string) –
api_host (string) –
entity_type (string) – One of: ‘metrics’, ‘items’, ‘regions’, or ‘sources’
search_terms (string) –

Yields:

dict – Result from search() passed to lookup() to get additional details Ex: { ‘id’: 274, ‘contains’: [779, 780, …] ‘name’: ‘Corn’,

‘definition’: ‘The seeds of the widely cultivated…’ }

See output of lookup(). Note that as with search(), the first result is the best match for the given search term(s).

api.client.lib.snake_to_camel(term)[source]¶

Convert a string from snake_case to camelCase.

>>> snake_to_camel('hello_world')
'helloWorld'

Parameters:	term (string) –
Returns:
Return type:	string

api.client.lib.universal_search(access_token, api_host, search_terms)[source]¶

Search across all entity types for the given terms.

Parameters:	access_token (string) – api_host (string) – search_terms (string) –
Returns:	Ex: [[5604, ‘item’], [10204, ‘item’], [410032, ‘metric’], ….]
Return type:	list of [id, entity_type] pairs

api.client.Client¶

API client with stateful authentication for lib functions.

api.client.gro_client¶

A Client with methods to find, and manipulate data series related to a crop and/or region.

This class offers convenience methods for some common scenarios

finding entities by name rather than ids
exploration shortcuts filling in partial selections
finding and saving data series for repeated use, including in a data frame

api.client.crop_model¶

A Client with methods to find, and manipulate data series related to a crop and/or region.

This class offers convenience methods for some common scenarios

finding entities by name rather than ids
exploration shortcuts filling in partial selections
finding and saving data series for repeated use, including in a data frame

api.client.batch_client¶

API client with support for batch asynchronous queries.

Gro API Client¶

api.client.lib¶

api.client.Client¶

api.client.gro_client¶

api.client.crop_model¶

api.client.batch_client¶

Indices and tables¶