RailKernel locomotive API

1. API contract

Base URL

https://railkernel.nl/api/v1

Resource

GET /locomotives.php

Current version

v1

Format

JSON encoded as UTF-8

Access

HTTPS with a Bearer API key

Required scope

rmdb:locomotive:read

Caching

Responses currently use Cache-Control: no-store

The endpoint retrieves either one exact locomotive variant or the collection belonging to one manufacturer and catalogue number. It does not provide bulk export, unrestricted search or mutation operations. An HTTP GET is the only supported method.

2. Authentication

Send the issued API key in the HTTP Authorization header. Never put an API key in a URL or query parameter.

Authorization: Bearer rk_live_<your-api-key>

Keys are shown only when issued, are assigned to one integration partner and can be revoked or replaced independently. Do not embed a key in browser JavaScript, a mobile application, a public repository or downloadable software. Calls must originate from a controlled server.

3. Requesting a locomotive

Preferred: stable RMDB identifier

Use the locomotive’s stable rmdb_uid as id. The colon and any other reserved characters must be URL-encoded by the HTTP client.

curl --fail-with-body \
  --request GET \
  --header "Authorization: Bearer ${RAILKERNEL_API_KEY}" \
  "https://railkernel.nl/api/v1/locomotives.php?id=piko%3A40375"

Collection: manufacturer and catalogue number

Supply exactly vendor and catalog_number to retrieve every locomotive variant recorded for that article. Both parameters are mandatory: a vendor or catalogue number on its own is rejected. The response remains a collection when only one locomotive is found.

curl --fail-with-body \
  --get \
  --header "Authorization: Bearer ${RAILKERNEL_API_KEY}" \
  --data-urlencode "vendor=piko" \
  --data-urlencode "catalog_number=40375" \
  "https://railkernel.nl/api/v1/locomotives.php"

Alternative: complete composite key

If no RMDB identifier is available, supply all four key components. catalog_suffix is required even when its value is empty, and variant_no starts at 1.

curl --fail-with-body \
  --get \
  --header "Authorization: Bearer ${RAILKERNEL_API_KEY}" \
  --data-urlencode "vendor=piko" \
  --data-urlencode "catalog_number=40375" \
  --data-urlencode "catalog_suffix=" \
  --data-urlencode "variant_no=1" \
  "https://railkernel.nl/api/v1/locomotives.php"

4. Response envelope

A successful request returns HTTP 200. The locomotive resource is always found at data.locomotive.

{
  "success": true,
  "data": {
    "locomotive": {
      "identity": {
        "id": "piko:40375",
        "vendor": "piko",
        "catalogNumber": "40375",
        "catalogSuffix": "",
        "variantNumber": 1
      },
      "product": { "name": "…" },
      "vendor": { "displayName": "Piko", "aliases": [] },
      "railway": { "company": "NS", "country": "NL" },
      "scale": { "gauge": "N", "ratio": "1:160" },
      "dimensions": { "lengthMm": 104 },
      "electrical": { "powerSystem": "DC", "digitalProtocol": "DCC" },
      "features": {},
      "technical": {},
      "decoders": [],
      "media": { "images": [], "manuals": [] },
      "links": { "manufacturerProductUrl": null, "retailers": [] },
      "pricing": { "msrp": null, "currency": null },
      "remarks": null,
      "provenance": { "source": null, "revision": null, "importedAt": null }
    }
  },
  "meta": {
    "apiVersion": "1",
    "generatedAt": "2026-08-27T08:15:30+00:00"
  }
}

The example is intentionally shortened. The complete set of returned fields is documented below. Consumers must read the JSON by field name and must not depend on property order.

Article collection response

A request containing only vendor and catalog_number returns HTTP 200 with an array at data.locomotives. Every array element has the same complete structure documented for data.locomotive. meta.count contains the number of returned variants.

{
  "success": true,
  "data": {
    "locomotives": [
      {
        "identity": {
          "id": "piko:40375",
          "vendor": "piko",
          "catalogNumber": "40375",
          "catalogSuffix": "",
          "variantNumber": 1
        },
        "product": { "name": "…" },
        "decoders": []
      }
    ]
  },
  "meta": {
    "apiVersion": "1",
    "generatedAt": "2026-08-28T08:30:00+00:00",
    "count": 1
  }
}

5. Complete field reference

All paths below are relative to data.locomotive.

Identity

Product

Manufacturer

Prototype, scale, dimensions and features

Technical locomotive data

Decoders and functions

Media, links, pricing and provenance

6. Missing data and media

• An unknown scalar value is returned as JSON null. Do not interpret it as zero, false or an empty string.
• An absent collection is returned as an empty array, for example decoders: [].
• Only decoder functions with a known description are included in functions[]. Use functionCount separately when present.
• availableLocally and localFileName describe RMDB holdings. They do not grant permission to reproduce media and they are not download URLs.
• Always respect the returned manufacturer link and copyright policies. A source URL does not automatically grant hotlinking, downloading or republication rights.

7. Errors

Error responses use the same predictable envelope:

{
  "success": false,
  "error": {
    "code": "locomotive_not_found",
    "message": "The requested locomotive was not found."
  },
  "meta": { "apiVersion": "1" }
}

8. Rate limits

The request allowance is assigned per API key. Do not hard-code a universal limit. Every authenticated response exposes the active one-minute window:

X-RateLimit-Limit

Maximum requests in the current one-minute window.

X-RateLimit-Remaining

Requests still available in that window.

X-RateLimit-Reset

Unix timestamp at which the window resets.

Retry-After

Seconds to wait after an HTTP 429 response.

Clients should cache records in their own application where appropriate, avoid repeated reads of an unchanged identifier and use exponential backoff for temporary failures.

9. Compatibility rules

• The major API version is part of the URL. Breaking changes require a new version such as /api/v2/.
• Version 1 may gain new optional fields or new values. Clients must ignore unknown properties and must not reject a response merely because it contains more data.
• Existing field meaning and type will not intentionally change within version 1.
• Use identity.id as the durable external reference. Catalogue numbers remain strings and must never be normalised numerically.
• meta.generatedAt is generated in UTC. Other source timestamps should also be treated as UTC unless a future field explicitly carries another offset.

10. Security requirements

• Use HTTPS only and validate the RailKernel TLS certificate.
• Store the API key in a secret store or server-side environment variable.
• Never log the full Authorization header. A short key prefix may be logged for diagnosis.
• Never send an API key by email, issue tracker, screenshot or source-code repository.
• Contact RailKernel immediately if a key may have leaked; the key can be revoked without affecting other clients.
• The API is read-only, but returned data and media metadata remain subject to their recorded source and copyright conditions.