https://www.dtn.com/agriculture/agribusiness/ecofield-data/
API docs by Redocly

DTN EcoField™ and Agriculture Core API (1.0.0)

Download OpenAPI specification:

DTN EcoField™ API Team: agintel@dtn.com URL: https://www.dtn.com/agriculture/agribusiness/ecofield-data/

Introduction

Welcome to the EcoField API documentation. EcoField Data presents a revolutionary approach to agricultural emissions analysis, offering unparalleled precision and depth in field-level emission information. At the heart of this product lies a sophisticated integration of diverse data sources and cutting-edge models, designed for those who seek detailed insights into the environmental impact of farming practices.

Key Features:

  • Comprehensive Data Integration: EcoField Data harnesses the power of FMID data, satellite imagery, and the FarmTrak survey information from Kynetec. This unique combination ensures a rich, multi-dimensional view of agricultural landscapes with the ability to integrate directly into customers' management or BI tools using our AgCore API.
  • Advanced Satellite Imagery Analysis: Utilizing cutting-edge satellite technology, EcoField Data provides accurate, up-to-date visual representations of farming areas. This allows for precise monitoring and assessment of on-ground conditions.
  • Insightful Survey Information: The integration of FarmTrak survey results adds a critical layer of qualitative data, offering insights into farming practices and trends that shape emission patterns.
  • Small Area Estimations: This feature enables a more localized and accurate analysis, ensuring that the emission data is not just a broad estimate but is reflective of specific conditions and practices in targeted areas.
  • Robust Emission Modeling: At the core of EcoField Data are the Cool Farm Tool and GREET models, known for their accuracy and active use in several programs in calculating emissions. These models transform the gathered data into actionable emission insights, reflecting the impact of various farming practices.
  • Field-Level Emission Information: With a focus on granularity, EcoField Data delivers emission information at the field level, making it an indispensable tool for companies trying to reach their emission goals, environmental scientists, and producers. This level of detail supports informed decision-making for sustainable farming practices.
  • Variety of On-Farm Practices Analysis: Whether it's crop rotation, fertilization methods, or irrigation practices, EcoField Data evaluates a wide range of agricultural practices and their environmental implications.

Applications

This API caters to a wide range of users and applications, including:

  • Emergency alert systems
  • Software developers building weather applications
  • Travel planning websites
  • Climate research projects

This interactive documentation will get you up to speed on setting up requests, understanding responses, and leveraging the EcoField API for your needs.

Visit the EcoField™ data product page for more information.

Getting Started

To get started, all users need their own client ID and client secret. Please contact an account manager or the DTN sales team to obtain these. Then, review the Authentication section to learn how to request an API access token. Do not share or use others' API credentials, since doing so may compromise information security.

Making requests

Starting off your journey with the the EcoField API couldn't be easier. We've provided a variety of options to suit your needs and comfort level: Interactive Documentation: Our interactive documentation is a great starting point. Simply navigate to the "Authentication" section, insert your credentials, and you'll obtain an access token behind the scenes. Then, explore the API endpoints described in the Endpoints section.

1. Interactive documentation: Navigate to the Authentication section on this page, insert credentials to obtain an access token, then explore the API endpoints described in the Endpoints section.

2. Postman collection: For a hands-on approach, consider downloading this Postman collection. Insert credentials and start testing the API in Postman's interactive application.

3. Writing code: Ready to start coding? Try the Python example below, replacing client_id and client_secret with proper credentials. This invokes the API endpoint with a GET request and prints the response.

  # --- Obtain an API access token ---
    import requests

    # --- Obtain an API access token ---
    authUrl = 'https://api.auth.dtn.com/v1/tokens/authorize'
    body = {
        'grant_type': 'client_credentials',
        'client_id': '...insert your client id here...',
        'client_secret': '...insert your client secret here...',
        'audience': 'https://ecofield.dtn.com'
    }
    
    response = requests.post(authUrl, json=body)
    access_token = response.json()['data']['access_token']
    
    # --- Invoke the API ---
    api_base_url = 'https://agcore-api.prd.ag.zones.dtn.com/api/v1/'
    
    endpoint = 'land/soil?limit=5"'
    headers = {'Authorization': 'Bearer ' + access_token, 'Content-Type': 'application/json'}
    response = requests.get(api_base_url + endpoint, headers=headers)
    
    # --- Print the response ---
    print(response.json())

License Restrictions

EcoField™ is licensed by crop and geographic region. Speak with your sales representative for details.

/api/v1/health-check

Get a message to prove the API is responding.

Returns a message to indicate the API is up and running.

Responses

Response samples

Content type
application/json
{
  • "message": "works"
}

/api/v1/codes/carbon-specifications

Codes and descriptions for carbon specification ID objects.

Returns a carbon specification ID object and its description type.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/api/v1/codes/direct-energy-categories

Direct energy category type codes and descriptions.

Returns direct energy category codes and descriptions of a given Direct energy category Type.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

/api/v1/codes/direct-energy-sources

Direct energy source type codes and descriptions.

Returns direct energy source codes and descriptions of a given Direct energy source Type.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

/api/v1/codes/tillage-types

All tillage type ids and descriptions.

Returns all tillage types.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

/api/v1/codes/tillage-types/{id}

Tillage type id and descriptions.

Returns the id and description of the tillage type queried.

Authorizations:
bearerAuth
path Parameters
id
required
number
Example: 1

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "description": "Full"
}

/api/v1/codes/power-source-types

All power source type ids and descriptions.

Returns all power source types.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

/api/v1/codes/power-source-types/{id}

Power source type id and descriptions.

Returns the id and description of the power source type queried.

Authorizations:
bearerAuth
path Parameters
id
required
number
Example: 1

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "description": "Natural lake/pond"
}

/api/v1/codes/water-source-types

All water source type ids and descriptions.

Returns all water source types.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

/api/v1/codes/water-source-types/{id}

Water source type id and descriptions.

Returns the id and description of the water source type queried.

Authorizations:
bearerAuth
path Parameters
id
required
number
Example: 1

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "description": "Natural lake/pond"
}

/api/v1/land/{landId}/cover-crop

Cover crop data by year and landID.

Returns a list of cover crop and crop type data.

Authorizations:
bearerAuth
path Parameters
landId
required
integer

Numeric ID of the land to get.

query Parameters
year
number

An array or singular year of data to be returned. If not provided then all available years data will be returned.

limit
number

The maximum response amount desired, if no limit all matching results will be returned.

offset
number

The offset of the last previously returned pagination results. To be used with limit for pagination.

Responses

Response samples

Content type
application/json
{}

/api/v1/land/emissions

Emissions released.

Returns a list of emissions data associated with a list of land ids.

Authorizations:
bearerAuth
query Parameters
limit
number

The maximum response amount desired, if no limit all matching results will be returned.

offset
number

The offset of the last previously returned pagination results. To be used with limit for pagination.

Request Body schema: application/json
required

List of primary keys for land objects.

landIds
required
Array of numbers[ items >= 1 ]
reportingYear
Array of numbers

Responses

Request samples

Content type
application/json
{
  • "landIds": [
    ],
  • "reportingYear": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "links": {},
  • "count": 4
}

/api/v1/land/energy-consumption

Energy consumption data for a land ID.

Returns farm/facility energy consumption data for an associated list of land IDs.

Authorizations:
bearerAuth
query Parameters
limit
number

The maximum response amount desired, if no limit all matching results will be returned.

offset
number

The offset of the last previously returned pagination results. To be used with limit for pagination.

Request Body schema: application/json
required

List of land IDs.

landIds
required
Array of numbers[ items >= 1 ]
reportingYear
Array of numbers

Responses

Request samples

Content type
application/json
{
  • "landIds": [
    ],
  • "reportingYear": [
    ]
}

Response samples

Content type
application/json
{}

/api/v1/land/fertilizers

Fertilizer usage.

Returns a list of fertilizer usage data associated with a list of land ids.

Authorizations:
bearerAuth
query Parameters
limit
number

The maximum response amount desired, if no limit all matching results will be returned.

offset
number

The offset of the last previously returned pagination results. To be used with limit for pagination.

Request Body schema: application/json
required

List of primary keys for land objects.

landIds
required
Array of numbers[ items >= 1 ]
reportingYear
Array of numbers

Responses

Request samples

Content type
application/json
{
  • "landIds": [
    ],
  • "reportingYear": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "links": {},
  • "count": 51
}

/api/v1/land/machinery

Machinery data.

Returns a list of machinery data associated with a list of land ids.

Authorizations:
bearerAuth
query Parameters
limit
number

The maximum response amount desired, if no limit all matching results will be returned.

offset
number

The offset of the last previously returned pagination results. To be used with limit for pagination.

Request Body schema: application/json
required

List of primary keys for land objects.

landIds
required
Array of numbers[ items >= 1 ]
reportingYear
Array of numbers

Responses

Request samples

Content type
application/json
{
  • "landIds": [
    ],
  • "reportingYear": [
    ]
}

Response samples

Content type
application/json
{}

/api/v1/land/management/practices

Land management practices.

Returns a list of Land management practices associated with a list of land ids.

Authorizations:
bearerAuth
query Parameters
limit
number

The maximum response amount desired, if no limit all matching results will be returned.

offset
number

The offset of the last previously returned pagination results. To be used with limit for pagination.

Request Body schema: application/json
required

List of primary keys for land objects.

landIds
required
Array of numbers[ items >= 1 ]
reportingYear
Array of numbers

Responses

Request samples

Content type
application/json
{
  • "landIds": [
    ],
  • "reportingYear": [
    ]
}

Response samples

Content type
application/json
{}

/api/v1/land/pesticides

Pesticide usage

Returns a list of pesticide usage data associated with a list of land ids.

Authorizations:
bearerAuth
query Parameters
limit
number

The maximum response amount desired, if no limit all matching results will be returned.

offset
number

The offset of the last previously returned pagination results. To be used with limit for pagination.

Request Body schema: application/json
required

List of primary keys for land objects.

landIds
required
Array of numbers[ items >= 1 ]
reportingYear
Array of numbers

Responses

Request samples

Content type
application/json
{
  • "landIds": [
    ],
  • "reportingYear": [
    ]
}

Response samples

Content type
application/json
{}

/api/v1/land/{landId}/production

Get a list of land objects and their EcoField data.

Returns a list of land objects that are passed from the body parameters and returns the land EcoField data from every year associated with with those land objects.

Authorizations:
bearerAuth
path Parameters
landId
number >= 1

A land id for a given search.

query Parameters
year
number

An array or singular year of data to be returned. If not provided then all available years data will be returned.

Responses

Response samples

Content type
application/json
{}

/api/v1/land/production

Get a list of land objects and their EcoField data.

Returns a list of land objects that are passed from the body parameters and returns the land EcoField data from every year associated with with those land objects.

Authorizations:
bearerAuth
query Parameters
land-id
number >= 1

A comma separated list of land ids for a given search.

limit
number

The maximum response amount desired, if no limit all matching results will be returned.

offset
number

The offset of the last previously returned pagination results. To be used with limit for pagination.

year
number

An array or singular year of data to be returned. If not provided then all available years data will be returned.

Request Body schema: application/json
optional

DEPRECATED - body parameters will be removed from this endpoint June 1 2024. List of primary keys for land objects.

landIds
required
Array of numbers[ items >= 1 ]

Responses

Request samples

Content type
application/json
{
  • "landIds": [
    ]
}

Response samples

Content type
application/json
{}

/api/v1/party/land

Get a list of party objects and their land EcoField data.

Returns a list of party objects that are passed from the body parameters and returns the landId and EcoField data from every year associated with with those party objects.

Authorizations:
bearerAuth
query Parameters
party-id
number

Comma separated number list of the primary keys for parties searched.

limit
number

The maximum response amount desired, if no limit all matching results will be returned.

offset
number

The offset of the last previously returned pagination results. To be used with limit for pagination.

year
number

An array or singular year of data to be returned. If not provided then all available years data will be returned.

Request Body schema: application/json

DEPRECATED - body parameters will be removed from this endpoint June 1 2024. Please switch to query parameters. List of primary keys for party objects.

partyIds
required
Array of numbers[ items >= 1 ]

Responses

Request samples

Content type
application/json
{
  • "partyIds": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "links": {},
  • "count": 10
}

/api/v1/land/irrigation

Search irrigation data based on landId.

Returns irrigation data associated with the landId.

Authorizations:
bearerAuth
query Parameters
land-id
number (landId)
Example: land-id=12345

The land-id associated with the requested data. This parameter is optional.

year
number

An array or singular year of data to be returned. If not provided then all available years data will be returned.

limit
number

The maximum response amount desired, if no limit all matching results will be returned.

offset
number

The offset of the last previously returned pagination results. To be used with limit for pagination.

Responses

Response samples

Content type
application/json
{}

/api/v1/land/crop/production

Land crop production.

Returns a list of Land Production data associated with a list of land ids.

Authorizations:
bearerAuth
query Parameters
limit
number

The maximum response amount desired, if no limit all matching results will be returned.

offset
number

The offset of the last previously returned pagination results. To be used with limit for pagination.

Request Body schema: application/json
required

List of primary keys for land objects and reporting years.

landIds
required
Array of numbers[ items >= 1 ]
reportingYear
Array of numbers[ items >= 2014 ]

Responses

Request samples

Content type
application/json
{
  • "landIds": [
    ],
  • "reportingYear": [
    ]
}

Response samples

Content type
application/json
{}

/api/v1/land/drainage/class-types

Land drainage class types.

Returns a list of drainage class types.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

/api/v1/land/drainage/class-types/{typeId}

Land drainage class types.

Returns a list of drainage class types.

Authorizations:
bearerAuth
path Parameters
typeId
required
number

This field is the numeric primary key for drainage class objects. If one is entered one drainage class type is returned. If not then all class types are returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/api/v1/land/fertilizers/production-regions

IDs and descriptions for fertilizer production regions.

Returns a list of fertilizer production region ids and descriptions.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

/api/v1/land/frequency-types

Land frequency types.

Returns a list of land frequency types.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

/api/v1/land/frequency-types/{typeId}

Land frequency types.

Returns a list of land frequency types.

Authorizations:
bearerAuth
path Parameters
typeId
required
number

This field is the numeric primary key for frequency types objects. If one is entered one frequency type is returned. If not then all types are returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/api/v1/land/map/unit/kind-types

Land map unit types.

Returns a list of land map unit types.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

/api/v1/land/map/unit/kind-types/{typeId}

Land map unit types.

Returns a list of land map unit types.

Authorizations:
bearerAuth
path Parameters
typeId
required
number

This field is the numeric primary key for map unit types objects. If one is entered one map unit type is returned. If not then all types are returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/api/v1/land/farm/class-types

Land farm class types.

Returns a list of farm class types.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

/api/v1/land/farm/class-types/{typeId}

Land farm class types.

Returns a list of farm class types.

Authorizations:
bearerAuth
path Parameters
typeId
required
number

This field is the numeric primary key for land farm class objects. If one is entered one farm class type is returned. If not then all class types are returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/api/v1/land/{landId}/soil

Get soil data based on landId.

Returns a list of soil data for the associated landId field.

Authorizations:
bearerAuth
path Parameters
landId
required
number >= 1

The primary key for land objects.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/api/v1/land/pesticides/categories

IDs and descriptions for pesticide categories types.

Returns a list of pesticide category ids and descriptions.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

/api/v1/land/soil

Search land data based on landId and season code.

Returns land data associated with the landId and from the search parameter associated with the given season code.

Authorizations:
bearerAuth
query Parameters
land-id
number (landId)
Example: land-id=12345

The land-id associated with the requested data. This parameter is optional and only one of land-id or mapUnitKey may be passed in. Not both.

map-unit-key
number >= 1

The mapUnitKey associated with the requested data. This parameter is optional and only one of land-id or mapUnitKey may be passed in. Not both.

limit
number

The maximum response amount desired, if no limit all matching results will be returned.

offset
number

The offset of the last previously returned pagination results. To be used with limit for pagination.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "links": {},
  • "count": 553
}

/api/v1/land/soil/summary

Search ecofield soil data based on landId.

Returns ecofield soil data associated with the landId.

Authorizations:
bearerAuth
query Parameters
land-id
number (landId)
Example: land-id=12345

The land-id associated with the requested data. This parameter is optional and only one of land-id or mukey may be passed in. Not both.

limit
number

The maximum response amount desired, if no limit all matching results will be returned.

offset
number

The offset of the last previously returned pagination results. To be used with limit for pagination.

year
number

An array or singular year of data to be returned. If not provided then the most recent year from partition table years will be returned.

Responses

Response samples

Content type
application/json
{}

/api/v1/land/weather

Search weather data based on landId.

Returns weather data associated with the landId.

Authorizations:
bearerAuth
query Parameters
land-id
number (landId)
Example: land-id=12345

The land-id associated with the requested data. This parameter is optional.

year
number

An array or singular year of data to be returned. If not provided then all available years data will be returned.

limit
number

The maximum response amount desired, if no limit all matching results will be returned.

offset
number

The offset of the last previously returned pagination results. To be used with limit for pagination.

Responses

Response samples

Content type
application/json
{}

/api/v1/machinery/fuel/types

Codes and descriptions for machinery fuel types.

Returns a list of machinery fuel types and their descriptions.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

/api/v1/machinery/types

Codes and descriptions for machinery types.

Returns a list of machinery types and their descriptions.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

/api/v1/machinery/types/{machineryId}

Code and description for machinery type.

Returns a single object of machinery type and it's description.

Authorizations:
bearerAuth
path Parameters
machineryId
required
number

This field is the numeric primary key for machinery type objects. If one is entered one machinery type object is returned. If not then all machinery type objects are returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/api/v1/party/phone-scores

Phone score reference data for party data.

Returns a phone score reference data.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

/api/v1/party/phone-scores/{scoreId}

Phone score reference data for party data.

Returns a phone score reference data.

Authorizations:
bearerAuth
path Parameters
scoreId
required
number

This field is the numeric primary key for phone scores. If one is entered one score object is returned. If not then all score objects are returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/api/v1/party/process-codes

Process codes reference data.

Returns a process codes reference data.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

/api/v1/party/process-codes/{codeId}

Process codes reference data.

Returns a process codes reference data.

Authorizations:
bearerAuth
path Parameters
codeId
required
string

This field is the primary key for process codes. If one is entered one process code object is returned. If not then all codes objects are returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/api/v1/party/source-codes

Source codes reference data.

Returns a source codes reference data.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

/api/v1/party/source-codes/{codeId}

Source codes reference data.

Returns a source codes reference data.

Authorizations:
bearerAuth
path Parameters
codeId
required
string

This field is the primary key for source codes. If one is entered one source code object is returned. If not then all codes objects are returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/api/v1/products/ecofield/users/licenses

List of accessible Fips codes and LCI Ids.

Returns a list of accessible Fips codes and LCI Ids associated with a users license in the ecofield product.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "fipsCodes": [
    ],
  • "lciIds": [
    ]
}