Locations

A location is the place where displays are installed: name, address, time zone, optionally the position on the map, the federal state, the opening hours, and the venue type. This page lists the fields, the routes, the assignment of a display, and the other places where the location appears.

What a location is#

A folder above displays, not a second tenant. It carries no permissions, no licenses, and no inventory of its own. A display points to it with locationId, and there is no tighter binding than that. Tags and video walls remain what they are: The location does not replace them, it answers a different question.

The time zone belongs to the location, not to the display: Two displays in the same room never have two different ones.

The routes#

curl -sS -X POST "$SZENERA_API/v1/locations" \
  -H "Authorization: Bearer $SZENERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Filiale Nord",
        "timeZone": "Europe/Berlin",
        "address": { "street": "Nordstraße 12", "postalCode": "30159", "city": "Hannover", "country": "DE" }
      }'

Assign a display#

The assignment does not go through the location route but through the display: A location is a master data field of the display, like its name.

curl -sS -X PATCH "$SZENERA_API/v1/players/ply_01KFB7QPW0PLAYER0000000001" \
  -H "Authorization: Bearer $SZENERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "If-Match: 3" \
  -d '{ "locationId": "loc_01KFB7QPW0LOCATION00000001" }'

"locationId": null detaches the display again. A location never takes displays down with it: An occupied location cannot be deleted, so the displays are moved or detached first. When a display gets a different location or none at all, it rebuilds its snapshot immediately: Opening hours, pharmacies on duty, weather, and time zone follow the new location.

Opening hours#

openingHours carries the weekly hours and the special days. The times are wall-clock times in the time zone of the location.

What applies on a given day follows a fixed order of precedence: a special day, otherwise a statutory holiday of the federal state (closed), otherwise the weekly hours. The platform does not store the holidays. It calculates them per federal state from the date of Easter and the state holidays. Holidays of individual municipalities are entered by the organization as a special day.

curl -sS -X PATCH "$SZENERA_API/v1/locations/loc_01KFB7QPW0LOCATION00000001" \
  -H "Authorization: Bearer $SZENERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "3"' \
  -d '{
    "region": "DE-HH",
    "openingHours": {
      "weekly": {
        "mon": [{ "opens": "08:30", "closes": "13:00" }, { "opens": "14:00", "closes": "18:30" }],
        "sat": [{ "opens": "09:00", "closes": "14:00" }]
      },
      "specialDays": [
        { "startDate": "2026-12-24", "endDate": "2026-12-24", "label": "Heiligabend",
          "closed": false, "windows": [{ "opens": "08:30", "closes": "12:00" }] }
      ]
    }
  }'

If the weekly hours, special days, federal state, or time zone change, the event fleet.location.opening-hours-changed is raised in addition to fleet.location.updated. All displays of the organization then rebuild their snapshot, because a widget can show the hours of every location, not only its own. A display whose snapshot stays the same receives nothing, and the others show the new times after a few seconds. The same applies when a location is deleted.

Where else the location appears#

If something goes wrong#

The three Location.* codes are listed with meaning, trigger, and status under Error codes: devices, playback, notifications, operations.

Related#

• Concurrent changes: ETag and If-Match
• Commands for your organization
• Handbook: Locations