Frequently Asked Questions: TellusLabs

Who is Tellus Labs?

TellusLabs is a Boston-based satellite imagery and machine learning company, founded in 2016, that builds environmental intelligence technology. In 2016 and 2017, TellusLabs’ agricultural insights product, Kernel, predicted U.S. soy and corn yield estimations ahead of  estimation data released by the U.S. government.

What type of data does TellusLabs provide?

TellusLabs provides satellite-based metrics related to agriculture and estimations on plant health derived from that data.

What is NDVI?

NDVI (Normalized Difference Vegetation Index) is a satellite-derived measurement for quantifying the presence or absence of live green vegetation.  NDVI is perhaps the most widely known satellite-derived vegetation index, and this measurement is subsequently used by many in the agriculture space to estimate  general health of a crop.  However, not all NDVI measurements are created equal.  At TellusLabs, we take a unique, science-driven approach to calculating NDVI that elevates our metric from a simple vegetation index to a truly refined, agriculture-focused, crop-specific science-grade estimation insight.  You can learn more about the TellusLabs approach to NDVI in our TellusLabs Crop Indices whitepaper.

What is TL CHI?

TL CHI, otherwise known as the TellusLabs Crop Health Index, is a proprietary, satellite-derived agricultural signal which estimates the overall health of a particular crop.  The design process for TL CHI was informed by well-established metrics like NDVI and EVI (Enhanced Vegetation Index) that capitalize on the physical properties of photosynthesizing plants.  However, TellusLabs’  focus on agriculture versus generalized vegetation allows  us to tailor the way the spectral information is combined in the index.  TL CHI uses a ratio of spectral bands that  seek to best capture  changes in crop health which may be  linked to end-of-season outcomes, resulting in TL CHI showing a promising dynamic range in response to yield.  To learn more about all aspects of TL CHI, please refer to our TellusLabs Crop Indices whitepaper.

How do I order the data?

You can order the data through CME DataMine, CME Group’s self-service cloud solution for historical and alternative datasets.

What is the file format of the TellusLabs data?

The files are delivered in .CSV.

What is the average daily file size?

The average daily file ranges from 5KB-10KB in size.

How many files are available per day?

Each country/crop/metric combination corresponds to an individual file.

For example, if you are subscribed to "Brazil, TL CHI, corn", you will receive a single file. If you are subscribed to "Brazil, TL CHI" for both corn and soy, then you will receive two files: one for corn and another for soy. If a user subscribes to all TellusLabs datasets they will receive 12 files a day.

What is the delivery frequency of the data?

The files are delivered once per day.

What time is delivery of the data each day?

All files are delivered to CME Group by 9:00 a.m. Eastern Time (ET).

Are files compressed?

Yes, the files are compressed.

Can you provide me a sample file for the CHI dataset?

Yes, click here to download a sample file.

Can you provide me a sample file for the NDVI dataset?

Yes, click here to download a sample file.

How far back, historically, is data available?

The files go back six years (since July 2011) for the Brazil and Argentina regions and 15 years (since January 2003) for the United States.

What is the geo_level field?

The geo_level field is used to indicate the level of geographic granularity being reported for the given metric/date/crop. By geographic granularity, it is referring to measurements like National, State or County.

Since these geographic divisions are named differently across countries, this has been abstracted into a single value.

What do the geo_level values mean?

Level_1 is National, level_2 is State/Province.

What is the geo_id field?

The geo_id field is a numeric identifier for a given geography.

For example, in the United States, the state of Iowa has a geo_id value of 19.

These numeric identifiers make it easier to analyze the data and combine it with other datasets. The values are country-specific.

For example, while 19 is the geo_id value for Iowa in the United States, 19 is also the geo_id value for Rio de Janeiro in Brazil.

How can I identify a unique geography?

A unique geography can be identified by combining the values from three fields: country_iso, geo_level and geo_id. Combining these three fields will give a unique geography across all of the TellusLabs datasets.

For example, USA, level_2, 19 will give the unique geography for the state of Iowa in the U.S.

Why are there occasionally a different number of records for one date versus another?

Since the data relies on satellites, there are occasionally days during which cloud cover or other factors prohibit data collection for a specific geography. There are many systems in place to mitigate this scenario, but there will still be occasions for which the data collection for a specific geography on a given date might not meet our thresholds for processing. For this reason, there may occasionally be specific geographies omitted for certain dates.

Where can I obtain a reference guide for the different Geo Levels?

For a reference guide for the different Geo Levels please click here.

Who do I contact if I have any issues with the data or CME DateMine?

For inquiries related to CME DataMine contact the Global Command Center (GCC), Sundays 2 p.m. – Fridays 4:30 p.m.

U.S.: +1 800 438 8616
Europe: +44 20 7623 4747
Asia: +65 6532 5010

Data Structure

Field Name CSV Column Example Value Supported Values Description
Geo Level A level_1 level_1, level_2 Location- either National (level_1) or State level (level_2)
Country ISO B BRA ARG, BRA, USA Country of crop being measured
Geo ID C 19 [00 through 54] Geographic Identifier
Geo Display Name D BRAZIL [Any name of a state/province within the U.S., Argentina, or Brazil. Or the name of the country itself]   Common name for Geography
Metric Date E 2018-03-09 [Any valid date] Crop that is being measured
Crop F corn corn, soy Crop that is being measured
Metric G .623009 [Any valid metric value, traditionally from -0.020000 through 0.920000] Metric Value (NDVI or CHI)

API Documentation

List

You can query a list of entitled files using this api call, with optional criteria to limit the number of results returned.

Criteria

Name Description Required Type
dataset Dataset the user is querying. In this case, it should always equal “telluslabs”   Yes String
exchangecode The country’s files that the user is wanting to list.   No String
yyyymmdd Report date. Accepted format is yyyymmdd.   Example: 20180312 No String
limit Amount of results per request.   A paging information will return with offset information. No int
offset Pagination mechanism   Use the offset returned by previous query for previous or next page. No int
firstfid Alternative pagination mechanism Use the firstfid returned in the paging section to query previous page No String
lastfid Use the lastfid returned in the paging section to query next page No String

Syntax:

curl --user {{UNO_API_KEY}}:{{UNO_API_PASSWORD}} 'https://{{URL}}/cme/api/v1/list?{{criteria1}}={{val1}}&{{criteria2}}={{val2}}&{{criteriaN}}={{valN}}'
curl --user API_JOHNSMITH:12345
'https://datamine.cmegroup.com/cme/api/v1/list?dataset=telluslabs&exchangecode=USA

Response

Name Description Type
dataset Dataset of the file String
exchangecode Country of the file String
url Fully qualified download URL String
expiration Expiration date of file access String
productcode Will always be a * String
yyyymmdd TellusLabs report date String
checksum MD5 Checksum for data String
size File size in KB int
fid Unique identifier for file String
orderid Order number String

Sample response:

{
    "files": [
        {
            "dataset": "TELLUSLABS",
            "yyyymmdd": "20180318",
            "url": "https://datamineuat.cmegroup.com/cme/api/v1/download?fid=20180318-TELLUSLABS_USA_corn_CHI_0",
            "fid": "20180318-TELLUSLABS_USA_corn_CHI_0",
            "orderid": "3950",
            "exchangecode": "USA",
            "productcode": "*",
            "checksum": "9a8764d5a1967b6642bbad395cddb2b4",
            "size": 2477,
            "expiration": "2018-04-18",
            "s3url": "cme-antivirus/uat/clean/ophirh/20180318/TELLUSLABS_USA_corn_CHI_20180318.csv"
        },
        {
            "dataset": "TELLUSLABS",
            "yyyymmdd": "20180318",
            "url": "https://datamineuat.cmegroup.com/cme/api/v1/download?fid=20180318-TELLUSLABS_USA_corn_CHI_0",
            "fid": "20180318-TELLUSLABS_USA_corn_CHI_0",
            "orderid": "3950",
            "exchangecode": "USA",
            "productcode": "*",
            "checksum": "9a8764d5a1967b6642bbad395cddb2b4",
            "size": 2477,
            "expiration": "2018-04-18",
            "s3url": "cme-antivirus/uat/clean/ophirh/20180318/TELLUSLABS_USA_corn_CHI_20180318.csv"
        }
    ],
    "paging": {
        "previous": "",
        "next": "https://datamineuat.cmegroup.com/cme/api/v1/list?dataset=telluslabs&exchangecode=usa&limit=2&lastFid=20180318-TELLUSLABS_USA_corn_CHI_0&page=1"
    }
}

Download

You can download a file that you have access to using this api call.

Criteria

Name Description Required Type
fid File Id, available from the list api, case insensitive.   The fid format is: yyyymmdd-TELLUSLABS_[country]_[crop]_[analytic]_0   Example: 20180308-TELLUSLABS_USA_corn_CHI_0 Yes String

Syntax:

curl -J -O --user {{UNO_API_KEY}}:{{UNO_API_PASSWORD}} 'https://{{URL}}/cme/api/v1/download?fid={{val}}'
curl -J -O --user API_JOHNSMITH:12345
'https://datamine.cmegroup.com/cme/api/v1/download?fid=20180308-TELLUSLABS_USA_corn_CHI_0'

You can use “-o” option to name your own file:
curl --user API_JOHNSMITH:12345
'https://datamine.cmegroup.com/cme/api/v1/download?fid=20180308-TELLUSLABS_USA_corn_CHI_0' -o my_eod_file.gz

More about TellusLabs

About CME Group

As the world's leading and most diverse derivatives marketplace, CME Group is where the world comes to manage risk. Comprised of four exchanges - CME, CBOT, NYMEX and COMEX - we offer the widest range of global benchmark products across all major asset classes, helping businesses everywhere mitigate the myriad of risks they face in today's uncertain global economy.

Follow us for global economic and financial news.

CME Group on Twitter

CME Group on Facebook

CME Group on LinkedIn