Sending Signals¶

This page describes the HTTP request your monitoring system sends to report station availability, the validation rules applied to it, and the responses you can expect.

Endpoint¶

POST https://api.h2-stations.eu/import/v1/hrs-availability

Every request needs two headers:

Header	Value
`Authorization`	`Bearer <your-token>`
`Content-Type`	`application/json`

Example Request¶

The request body is a JSON array of signal objects. One request may carry signals for multiple stations.

curl -X POST https://api.h2-stations.eu/import/v1/hrs-availability \
  -H "Authorization: Bearer 64a3468a15386b0d93c853c3cd2ba043b66a30ec" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "hrs": "ABCDE",
      "datetime": "2026-06-11T09:41:00+02:00",
      "dispensers": [
        {"fuel_type": "700car", "available": true},
        {"fuel_type": "350bus", "available": false}
      ],
      "maintenance": false,
      "limitedly_available": false
    },
    {
      "hrs": "FGHIJ",
      "transmission_id": "tr-2041",
      "datetime": "2026-06-11T09:41:12+02:00",
      "dispensers": [
        {"fuel_type": "350car", "available": true}
      ],
      "maintenance": false,
      "limitedly_available": true
    }
  ]'

Before you copy-paste: replace the datetime values with the current time. Signals older than 5 minutes are rejected (see Validation Rules below).

Validation Rules¶

The payload must be a JSON array, even when it contains a single signal. Each signal object is validated independently against these rules:

hrs (string, required): the station's HRS ID, exactly five uppercase letters (pattern ^[A-Z]{5}$), issued by H2-Stations when the station is registered. The station must exist on the platform.

datetime (string, required): when the signals were measured, in ISO 8601 format including the UTC offset, e.g. 2026-06-11T09:41:00+02:00. The timestamp may not be older than 5 minutes and may not lie in the future (a tolerance of 30 seconds is allowed for clock skew). Stale or future-dated signals are rejected.

dispensers (array, required). One entry per fuelling option:

fuel_type (string, required): a fuelling-option identifier registered with H2-Stations, one of 700car, 350car, or 350bus. Unknown identifiers are rejected. The authoritative list is available via GET https://api.h2-stations.eu/import/v1/fuel-type.
available (boolean, optional): whether at least one dispenser providing this fuelling option can refuel. May be null or omitted. The fuelling option is then treated as if it were absent from the signal and its status becomes unknown.

maintenance (boolean, required): whether the whole station is in maintenance. There is no default. You must send it explicitly.

limitedly_available (boolean, required): whether the station is limitedly available. There is no default. You must send it explicitly. Note the field name: limitedly_available.

transmission_id (string, optional): identifier of the signal-transmission licence for a single HRS. You do not need it when hrs is given, and hrs is required in every signal, so in practice you can omit this field.

Include every fuelling option the station provides in every signal. Omitted options are set to unknown.

Responses¶

204 No Content: success¶

All signals were accepted. The response body is empty. There is no 200 OK with a body. Treat any 2xx handling in your client accordingly.

Acceptance does not by itself publish anything: whether your signals drive the public status depends on the station's transmission state (Live, Testing, or Inactive), which the HRS operator controls.

400 Bad Request: validation failure¶

At least one signal failed validation. The body is a JSON array with one entry per signal, in the same order as your request: an empty object {} for signals that passed, and an object mapping field names to error messages for signals that failed.

[
  {},
  {
    "datetime": [
      "The signal may not be older than 5 minutes."
    ],
    "dispensers": [
      {
        "fuel_type": [
          "Invalid fuelling option"
        ]
      }
    ]
  }
]

Signals are processed in order, and valid signals are accepted even when the overall response is 400. Inspect the error array to find out which entries were rejected, fix those, and resend only the failed signals if needed.

If the payload is not a JSON array at all, the response is a 400 with a single error object instead, e.g. {"non_field_errors": ["Expected a list of items but got type \"dict\"."]}.

401 Unauthorized: authentication failure¶

The Authorization header is missing, malformed, or carries a token that is unknown or has been deactivated. The body is {"detail": "<message>"}, e.g. {"detail": "Invalid token."}. No signals are processed.

500 / 503: server-side errors¶

500 Internal Server Error indicates an unexpected platform error. 503 Service Unavailable indicates temporary unavailability. Retry with backoff and contact H2-Stations if the condition persists.

What the Platform Logs¶

For each signal originator the platform keeps an API call log in one of three modes: disabled (nothing is recorded), errors only (only failed calls are recorded, the default), or always (every call is recorded, including successful ones). A log entry stores the request time, the response status code, the request body, and, for failed calls, the response body and error details. These raw API call logs are available to platform administrators. HRS operators can additionally trace your transmissions in the portal (last signal received, signal timeline, and reliability), so the operator and the H2-Stations team together are the first place to ask when debugging your integration.

After Acceptance¶

Accepted signals feed the per-fuelling-option status computation: the platform periodically evaluates the most recent signal for each station and derives an availability status per fuelling option, which is then published on the map and the data interfaces. How signals translate into statuses, including the 30-minute timeout and the priority of maintenance and limited-availability flags, is described in Availability Status.

Schema Reference¶

The authoritative, machine-readable schema is the interactive OpenAPI documentation at https://api.h2-stations.eu/import/v1/doc/.

Backlinks

For Signal Originators