Note: This document is for an older version of the Gro API Client. Please see the latest documentation.

Searching Data

To derive the insights you want from Gro’s data, you will first want to find the data you’re interested in. Below you will find some of the most useful tips on how to discover the data of greatest value to you.

Code snippets

Users may find that the Gro API is at its most powerful when used in conjunction with the Gro web application. The web app provides the most convenient format for selecting the data series that is of most interest to you. In our Add Data Series window, you can select entities of interest, and then other entities for which no data is available based on your selection will be filtered out from the remaining options. For example, after selecting the item “Corn” only metrics and regions that have data for ‘Corn’ will remain selectable.

Add data series example

Once you have created a chart with data that you want, you can take advantage of our Code Snippets feature to pull that data into your API client code.

Simply click on the Chart Dropdown Button, then select Export and API Client Code Snippets.

Code snippet dropdown

Every unique data series from your chart will now be available in a client.get_data_points function for easy copying and pasting into your code or command line.

Code snippet copy code

For charts that have multiple data series, you have the option to Select all unique data series, or to select the individual series that are of greatest interest to you.

Code snippet select all

Get data series

Instead of searching for all the individual entity IDs required to create a data series, the groclient.GroClient.get_data_series() method will return a list of all the data series available for the filters you have supplied. For example, if you are interested in Russian Oats you could use the following code to find out all the available data series that have “Oats” (item_id = 327) as the item and “Russia” (region_id = 1168) as the region:

client.get_data_series(item_id='327',region_id='1168')

Lookup contains

Our ontology is defined in terms of a graph, with metrics/items/regions containing others. In each case, you can see the 'contains' property in the output of client.lookup(type, id). For example:

client.lookup('items', 10009)['contains']

will return a list of items ids for items that are cereals (item_id = 10009): [..., 274, 422, ...]. Once you have those ids, you can use the groclient.GroClient.lookup() function on each one to find more info, like their names, e.g.: client.lookup('items', 274)['name'] will return Corn.

Get descendants

Using the lookup() method, you can get an entity’s list of direct children (i.e. country→provinces). However, you may want all of the lower level regions that belong to a higher level region (i.e. country→provinces, districts, coordinates, etc.). To do this, you can specify the region level when using the groclient.GroClient.get_descendant() method:

To look up all descendants of region 1029 (Brazil) that are of level 4 (provinces):

from groclient.lib import REGION_LEVELS
provinces_of_brazil = client.get_descendant('regions', 1029, descendant_level=REGION_LEVELS['province'])

To look up all descendants of region 1029 (Brazil) that are of level 5 (districts):

from groclient.lib import REGION_LEVELS
provinces_of_brazil = client.get_descendant('regions', 1029, descendant_level=REGION_LEVELS['district'])

For more information on region levels, please refer to the Special properties of regions section of Gro Ontology

Lookup belongs

If you want to find “what entities contain the given entity?” there is a method, groclient.GroClient.lookup_belongs() that just does that. For example:

UNITED_STATES = 1215
client.lookup_belongs('regions', UNITED_STATES)

will yield [{id: 15, name: 'North America', contains: [1215, 1037, ...], level: 2}, ...]