API Docs

Locales/languages

There are waste collection programs in many countries. And we always strive to provide our services in the language of the country in question.

This is easy to do in countries that only use one language. In fact, if your application is only ever used in countries with just one language, you don't need to implement anything from this section.

For multi-language countries however (e.g. Canada, the USA where Mexican Spanish is used more and more - we support it, or Switzerland in Europe with its German, French and Italian languages) a method was needed for your application to be able tell our API, which language the current user of your application wants to receive information in. This is what is described in this section.

Usually there is two steps needed to solve this problem:

  1. Your application asks our API, what languages are available for use. Our API sends you a list of languages. You decide on a language from the list, e.g. by displaying that list to the user to choose from, or making an automatic decision on the user's behalf based on their previous preferences.
  2. You then communicate the chosen language to our API in each of your requests.

List Available Locales/languages

Get a list of available locales. Only relevant for multi-lingual countries.

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/locales?access_token=...access_token...
Request parameter
parameter description
access_token the access_token acquired through OAuth

Example

curl -G \
  -d 'access_token=acce55acce55acce55acce55acce55acce55acce55acce55acce55acce55acce' \
  https://api.terracycle.com/en-US/v2/locales

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Language: en-US
{
  "locales": [
    {
      "locale": "en-US",
      "name": "English (US)"
    },
    {
      "locale": "es-US",
      "name": "Espa\u00f1ol (US)"
    }
  ]
}
field name description
locales top-level container for the list (array) of locales/languages
locale the commonly used/standardized short code for the locale - usually a combination of language code and country code; in this example en stands for English language, US stands for the USA, so the combination means US English
name human-readable common name for the locale/language - to display to the user to help language selection

Specify chosen locale/language

Simply provide an HTTP Accept-Language header with your API request specifying one of the locale values from above, and we will obey it and return the response in that locale/language.

Example: Accept-Language: en-US

If you specify a locale/language that was not listed by the request above, we will try to use the closest language available if we can guess one, or the default language (first language from the list above) if we could not guess which language would be similar.

This means you are free to use the user's system-wide locale/language preferences as default, and it will usually work. But please still provide the user with the option of calling up this list and choosing another language.

How to check if the proper locale is being used

All API endpoints explicitly tell what locale they deducted from your request and used in responding to it, in the Content-Language header: Content-Language: en-US

Locale/language on sign in and authorization screens

During the OAuth authorization flow (described on the Getting Started page) the sign in and authorization screens will be shown to your user by our servers.

The user will probably want to see these screens as well in their own language.

We do process and obey the Accept-Language header for these screens as well, so if your user's browser provides the correct languages in that header, you do not have to do anything, the screens will automatically be shown in the correct language.

In the case you do want to show these screens in another language listed in our language list above, please insert the locale as the first thing into the path of the URL you redirect the user to, and we will obey it and carry it forward to all screens we show to the user.

Example:

URL for default language:
https://api.terracycle.com/oauth/authorize

This will show the screens in the default language - the first one from the list above; in our example this will be en-US (US English).

URL for specified language
https://api.terracycle.com/es-US/oauth/authorize

This will show the screens in the specified language (assuming that language is listed above) - es-US (US Spanish).