Warning: This document is for the development version of Gro API Client. The main version is development.

API Reference

Basic Exploration

GroClient.lookup(entity_type, entity_id)

Retrieve details about a given id of type entity_type.

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

Parameters:
  • entity_type ({ 'metrics', 'items', 'regions', 'frequencies', 'sources', 'units' }) –
  • entity_id (int) –
Returns:

Example:

{ '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

GroClient.search(entity_type, search_terms)

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

Parameters:
  • entity_type ({ 'metrics', 'items', 'regions', 'sources' }) –
  • search_terms (string) –
Returns:

Example:

[{'id': 5604}, {'id': 10204}, {'id': 10210}, ....]

Return type:

list of dicts

GroClient.search_and_lookup(entity_type, search_terms, num_results=10)

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

For each result, yield a dict of the entity and it’s properties.

Parameters:
  • entity_type ({ 'metrics', 'items', 'regions', 'sources' }) –
  • search_terms (string) –
  • num_results (int) – Maximum number of results to return. Defaults to 10.
Yields:

dict – Result from search() passed to lookup() to get additional details.

Example:

{ '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).

GroClient.search_for_entity(entity_type, keywords)[source]

Returns the first result of entity_type that matches the given keywords.

Parameters:
  • entity_type ({ 'metric', 'item', 'region', 'source' }) –
  • keywords (string) –
Returns:

The id of the first search result

Return type:

integer

GroClient.get_data_series(**selection)

Get available data series for the given selections.

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

Parameters:
  • metric_id (integer, optional) –
  • item_id (integer, optional) –
  • region_id (integer, optional) –
  • partner_region_id (integer, optional) –
  • source_id (integer, optional) –
  • frequency_id (integer, optional) –
Returns:

Example:

[{ '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

Data Retrieval

GroClient.get_data_points(**selections)[source]

Get all the data points for a given selection.

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

Parameters:
  • metric_id (integer) –
  • item_id (integer) –
  • region_id (integer) –
  • partner_region_id (integer, optional) – partner_region refers to an interaction between two regions, like trade or transportation. For example, for an Export metric, the “region” would be the exporter and the “partner_region” would be the importer. For most series, this can be excluded or set to 0 (“World”) by default.
  • source_id (integer) –
  • frequency_id (integer) –
  • unit_id (integer, optional) –
  • start_date (string, optional) – all points with start dates equal to or after this date
  • end_date (string, optional) – all points with end dates equal to or after this date
  • show_revisions (boolean, optional) – False by default, meaning only the latest value for each period. If true, will return all values for a given period, differentiated by the reporting_date field.
  • insert_null (boolean, optional) – False by default. If True, will include a data point with a None value for each period that does not have data.
  • at_time (string, optional) – Estimate what data would have been available via Gro at a given time in the past. See /api/client/samples/at-time-query-examples.ipynb for more details.
Returns:

Example

[ {
    '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

Geographic

GroClient.get_geojson(region_id)

Given a region ID, return a geojson shape information

Parameters:region_id (integer) –
Returns:Example:
{ 'type': 'GeometryCollection',
'geometries': [{'type': 'MultiPolygon',
                'coordinates': [[[[-38.394, -4.225], ...]]]}, ...]}
Return type:a geojson object or None
GroClient.get_descendant_regions(region_id, descendant_level=None, include_historical=True)

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

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

Parameters:
  • region_id (integer) –
  • descendant_level (integer, optional) – The region level of interest. See REGION_LEVELS constant. If not provided, get all descendants.
  • include_historical (boolean, optional) – True by default. If False is specified, regions that only exist in historical data (e.g. the Soviet Union) will be excluded.
Returns:

Example:

[{
    '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

GroClient.get_provinces(country_name)[source]

Given the name of a country, find its provinces.

Parameters:country_name (string) –
Returns:Example:
[{
    '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

See also

get_descendant_regions()

Advanced Exploration

GroClient.lookup_belongs(entity_type, entity_id)

Look up details of entities containing the given entity.

Parameters:
  • entity_type ({ 'metrics', 'items', 'regions' }) –
  • entity_id (int) –
Yields:

dict – Result of lookup() on each entity the given entity belongs to.

For example: 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 }
GroClient.rank_series_by_source(series_list)

Given a list of series selections, for each unique combination excluding source, expand to all available sources and return them in ranked order. The order corresponds to how well that source covers the selection (metrics, items, regions, and time range and frequency).

Parameters:series_list (list of dicts) – See the output of get_data_series().
Yields:dict – The input series_list, expanded out to each possible source, ordered by coverage.

Pandas Utils

GroClient.get_df()[source]

Call get_data_points() for each saved data series and return as a combined dataframe.

Note you must have first called either add_data_series() or add_single_data_series() to save data series into the GroClient’s data_series_list. You can inspect the client’s saved list using get_data_series_list().

Returns:The results to get_data_points() for all the saved series, appended together into a single dataframe. See https://github.com/gro-intelligence/api-client/wiki/Data-Point-Field-Definitions
Return type:pandas.DataFrame
GroClient.add_data_series(**kwargs)[source]

Adds the top result of find_data_series() to the saved data series list.

For use with get_df().

Parameters:
  • metric (string, optional) –
  • item (string, optional) –
  • region (string, optional) –
  • partner_region (string, optional) –
  • start_date (string, optional) – YYYY-MM-DD
  • end_date (string, optional) – YYYY-MM-DD
Returns:

Return type:

None

See also

get_df(), add_single_data_series(), find_data_series()

GroClient.add_single_data_series(data_series)[source]

Save a data series object to the GroClient’s data_series_list.

For use with get_df().

Parameters:data_series (dict) – A single data_series object, as returned by get_data_series() or find_data_series(). See https://github.com/gro-intelligence/api-client/wiki/Data-Series-Definition
Returns:
Return type:None
GroClient.get_data_series_list()[source]

Inspect the current list of saved data series contained in the GroClient.

For use with get_df(). Add new data series to the list using add_data_series() and add_single_data_series().

Returns:A list of data_series objects, as returned by get_data_series().
Return type:list of dicts