API Docs

Statistics

Many people participate in waste collection. This statistics functionality provides three key numbers to show the volume of their total/combined collection efforts.

Get statistics

Get top-level statistics on collected waste.

Scope: public; this endpoint does not require a logged in user: you can use OAuth2.0 Client Credentials Flow as described in our Getting Started Guide

Request

GET https://api.terracycle.com/en-US/v2/stats?access_token=...access_token...
Request parameter
parameter description
access_token the access_token acquired through OAuth

Example

$ curl -G \
  --data 'access_token=acce55acce55acce55acce55acce55acce55acce55acce55acce55acce55acce' \
  https://api.terracycle.com/en-US/v2/stats

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Language: en-US
{
  "stats": {
    "people_collecting": 35413526,
    "waste_collected": 2494276733,
    "money_raised": 5491180.61,
    "money_raised_formatted": "$5,491,180.61"
  }
}
field name description
stats top-level container for the statistics
people_collecting estimated total number of people participating in waste collection
waste_collected estimated total waste units collected by all participants
money_raised estimated total amount of money raised for charitable purposes through waste collection - formatted as a computer-readable number with fractional point
money_raised_formatted this is the same number as money_raised above, but formatted for humans using the currency symbol and formatting conventions of the country

Get per city statistics

Get statistics on collected waste per city.

Scope: public

Request

GET http://api.terracycle.com/en-US/v2/stats/city?access_token=...access_token...
Request parameters
parameter description
access_token the access_token acquired through OAuth
brigade_ids
optional
only show statistics of shipments sent in for these brigades (collection programs)
format is comma-separated list of IDs, e.g.: 1,3,7
on_or_after
optional
only show statistics of shipments checked-in on or after the specified date
format is an ISO8601 date, e.g.: 2013-09-21. Without the timezone set, the country's one is used (e.g. US/Pacific for the US, ask if unsure).
before
optional
only show statistics of shipments checked-in before the specified date
format is an ISO8601 date, e.g.: 2013-09-21. Without the timezone set, the country's one is used (e.g. US/Pacific for the US, ask if unsure).

Example

$ curl -G \
  --data 'access_token=acce55acce55acce55acce55acce55acce55acce55acce55acce55acce55acce' \
  https://api.terracycle.com/en-US/v2/stats/city

Response

Success
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Language: en-US
{
  "city_stats":
  [
    {
      "units_collected": 5000000,
      "shipments_count": 200,
      "locality": "Miami",
      "region": "FL",
      "country_iso": "US"
    },
    {
      "units_collected": 3244,
      "shipments_count": 100,
      "locality": "Des Moines",
      "region": "IA",
      "country_iso": "US"
    }
  ]
}
field name description
city_stats top-level container for the statistics
units_collected estimated total waste units collected by all participants in that city
shipments_count number of shipments received from that city
locality name of city/town/settlement
region commonly used name or postal abbreviation/code for region within country (e.g. the two-letter codes for the states in the USA and provinces in Canada, etc.); present but null if the country does not use this
country_iso ISO 3166-1 code of the country
Invalid on_or_after date

When the on_or_after parameter is not an ISO8601 format date, e.g.: 2013-09-21

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8
Content-Language: en-US
{
  "error": "invalid-date",
  "message": "on_or_after is not a valid iso8601 date"
}
Invalid before date

When the before parameter is not in ISO8601 format date, e.g.: 2013-09-21

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8
Content-Language: en-US
{
  "error": "invalid-date",
  "message": "before is not a valid iso8601 date"
}