Getting Started

Learn how to read container codes (and other transportation/cargo relaed codes) using the Carmen Cloud Transportatio & Cargo API in less than 5 minutes!

Register to get your free lookups

First, if you haven't already done so, you need to register at the Cloud Dashboard. The free tier provides 2500 lookups which should be enough for running some tests.

Get your API key

After registering, log in to the Cloud Dashboard, scroll down until you see the box below, and copy your API key.

How authentication works

Recognition requests are authenticated with the API key itself: send it in the X-Api-Key header of each request, as shown below. That is all you need for this tutorial.

Everything beyond recognition — managing API keys, usage reports, event storage and webhooks — is done via the Carmen Cloud API, which instead expects a short-lived bearer token in the Authorization header. You get a token by exchanging your API key at the token endpoint; see the Authentication reference for details.

Find a test image

Find an image with a transportation code visible, or download this one for a quick test:

Choose a code type to read

Available code types are:

• eu-rail: European wagon and locomotive codes used across Europe to identify individual rail vehicles
• am-rail: American wagon and locomotive codes used across the American continent to identify individual rail vehicles
• truck: Identification codes used on trucks (ACCR, US DOT, Chassis)
• iso: ISO codes for containers and identification of intermodal loading units (ILU)

Send a request to the Transportation & Cargo API

Using your tool of choice, send the following POST request to the URL https://api.carmencloud.com/transport/<type> (substitute the region you have chosen in the previous section):

• Header: Content-Type: multipart/form-data
• Header: X-Api-Key: [YOUR_API_KEY]
• Field image: the test image with its appropriate content type (e.g. image/jpeg or image/png). Multiple images can be sent in a single request by using the image field multiple times.
• Field maxreads: the maximum number of codes to read (optional, default is 1)

For example, using the test image linked before:

cURL

curl -X POST 'https://api.carmencloud.com/transport/am-rail' \
-H 'X-Api-Key: [YOUR_API_KEY]' \
-H 'Content-Type: multipart/form-data' \
-F 'maxreads=1' \
-F "image=@transport-api-test-image.jpg;type=image/jpeg"

Python

import requests

with open("transport-api-test-image.jpg", "rb") as image:
    response = requests.post(
        "https://api.carmencloud.com/transport/am-rail",
        headers={"X-Api-Key": "[YOUR_API_KEY]"},
        data={"maxreads": 1},
        files={"image": ("transport-api-test-image.jpg", image, "image/jpeg")},
    )

response.raise_for_status()
print(response.json())

JavaScript

// Node.js 18+ (fetch, FormData and Blob are built in)
import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("maxreads", "1");
form.append(
  "image",
  new Blob([await readFile("transport-api-test-image.jpg")], { type: "image/jpeg" }),
  "transport-api-test-image.jpg"
);

const response = await fetch("https://api.carmencloud.com/transport/am-rail", {
  method: "POST",
  headers: { "X-Api-Key": "[YOUR_API_KEY]" },
  body: form,
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

tip

Prefer a ready-made client? Our SDKs wrap these calls for you: the Node.js client (@adaptive-recognition/carmen-cloud-client) and the Python package carmen-cloud-client (pip install carmen-cloud-client). The homepage has copy-paste examples in further languages.

The response will be a JSON object with the following structure:

{
  "data": {
    "codes": [
      {
        "code": "NFL049511",
        "confidence": 96,
        "imageResults": [
          {
            "found": true,
            "text": "NFL049511",
            "confidence": 96,
            "characters": [ ... ]
          }
        ],
        "engine": "cmocr-7.3.16.223:am_rail",
        "proctime": 321
      }
    ]
  },
  "nodename": "9f2f4fae-c858-49f9-a16d-12dc08042343 ([70]36549e57d4794a17a0c8bd1e10d2e065)",
  "nodetime": 421,
  "version": "1.0"
}

Further Reading

• Read the API reference