API docs by Redocly

Foodsteps API (1.0.0)

Download OpenAPI specification:

The Foodsteps API allows you to manage products and access their impact.

Getting Started

Examples of how to use our API can be found here.

Authentication

To request an API key contact support@foodsteps.earth. This key must be included in requests to the API via a X-Api-Key header. For example: curl 'https://api.foodsteps.earth/v1/products/' \
-H 'X-Api-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'

Common Terms

Product

A product is a food produced by your organisation. It is defined by its ingredients and production methods. An ingredient can be another of your organisation's products or a food you have purchased as an ingredient.

You must assign products an identifier called an externalId, this will uniquely identify your product within the Foodsteps platform. We recommend that products managed through integration with an existing system populate externalId with the unique identifier from that system.

Impact

Foodsteps calculates the environmental impact of your organisation’s products over several impact categories. These include GHG emissions, land use, and water use. Foodsteps reports impact intensity, provided as impact per KG of product, and impact per serving of product.

Determining the impact of a product is a complex calculation and may require substantial computation. In the majority of cases the impact is cached, but for an updated or newly created product it is possible for this calculation to take multiple seconds, or in extreme cases, multiple minutes. Where an ingredient of a product has never previously been assessed this time may be substantially longer as previously unseen ingredients are reviewed by an expert. See the current impacts endpoint for guidance on polling.

current-impacts

Current Impacts

Get the current impact of products. A new impact is calculated for a product whenever it is updated.

Impacts that have not finished calculating yet will have the status pending. Impacts that could not be calculated will have the status failed, along with information on why they failed.

Authorizations:
ApiKeyAuth
query Parameters
productExternalIds
required
Array of strings (Productexternalids)

Include products with these product external IDs. Can be provided multiple times (e.g., productExternalIds=id1&productExternalIds=id2)

Responses

Response samples

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

products

Products

List the products in your organization.

Authorizations:
ApiKeyAuth
query Parameters
externalIds
Array of strings (Externalids)
Default: ""

The external IDs of the products to retrieve. Can be provided multiple times (e.g. ?externalIds=id1&externalIds=id2)

page
integer (Page) >= 1
Default: 1

Page number for pagination

size
integer (Size) [ 1 .. 50 ]
Default: 10

Number of items per page

Responses

Response samples

Content type
application/json
Example
{
  • "products": [
    ],
  • "hasNextPage": false,
  • "hasPreviousPage": false,
  • "totalCount": 1,
  • "totalPages": 1
}

Create Or Update Products

Create or update products in your organization. If no product with a matching externalId exists a new product will be created. Otherwise the existing product will be updated.

Ingredients
Each ingredient has its own externalId. This is used to group identical kinds of ingredients across your products for modeling by the platform. If an ingredient is best modeled as another of your products, indicate that by providing the product's externalId in the subProductExternalId field.
Supplier
You can optionally provide supplier information. If a supplier with the same name already exists, it will be reused. Otherwise, a new supplier will be created.

When can externalId be omitted?By default externalId is mandatory. If you wish to use IDs provided by our system instead of your own, contact us about enabling this for your organization. If your organization has been configured this way, omitting the externalId field will cause a new product to be created with an externalId generated by Foodsteps.
Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
required
Array of objects (Products)

Responses

Request samples

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

Response samples

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

Delete Products

Delete products in your organization by external ID.

Authorizations:
ApiKeyAuth
query Parameters
externalIds
required
Array of strings (Externalids)

Responses

Response samples

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

tags

Tag Product Actions

Assign or unassign tags to products, creating the tags if they don't exist. The actions will be completed in the order they're passed. Note a small asymmetry: if you remove a tag from all products, we don't delete the tag.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
required
Array of objects (Actions)

Responses

Request samples

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

Response samples

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

versioned-impacts

Versioned Impacts

Get the version history of impacts for products in a given applicable date and month. For a given date and month, returns a list of applicable impact versions per product external ID. For the most recent versions it's possible that the impact has not been calculated yet, in which case the status will be pending.

The difference between the impact for the same productExternalId and same version for a different applicableDate represents real world change in the impact of that product between those applicable dates. The difference between the impact for the same productExternalId and same applicableDate for a different version represents a methodological change in the way the impact was calculated based on either changes to the source product data or Foodsteps's own methodology.

Authorizations:
ApiKeyAuth
query Parameters
productExternalIds
required
Array of strings

Include products with these product external IDs. Can be provided multiple times (e.g., productExternalIds=id1&productExternalIds=id2)

applicableDate
integer or null [ 1 .. 12 ]

Examples:

  • applicableDate=11 - Include impacts that are applicable in November

The month (1-12) that impacts are applicable to.

applicableYear
integer or null

Examples:

  • applicableYear=2025 - Include impacts that are applicable in 2025

The year that impacts are applicable to.

Responses

Response samples

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