Skip to content
HALOWERK

Datenwerk

timezone fair slot

Builds candidate slots in a UTC (or chosen) window at a fixed step and converts each to every participant's local time with luxon (IANA zones, DST-aware). Per participant the penalty is the number of meeting minutes outside their working hours on working days; minutes inside the unsocial band (default 22:00-07:00 local) count double. Slots touching the unsocial band or a non-working day of anyone are excluded unless allow_unsocial is true. Ranking: smallest maximum penalty, then smallest.

POST https://daten.halowerk.com/v1/timezone-fair-slot

Inputs

Fields of the published input schema
FieldTypeRequiredDescription
participantsarrayYesPeople or teams with their own zone and hours.
date_fromstringYesFirst day of the search window (in window_timezone).
date_tostringYesLast day of the search window (inclusive).
window_timezonestringNo
duration_minutesintegerYes
step_minutesintegerNo
unsocial_startstringNoLocal time from which hours count as unsocial.
unsocial_endstringNoLocal time until which hours count as unsocial.
allow_unsocialbooleanNo
rotationintegerNoNumber of different slots to rotate a recurring meeting through.
max_resultsintegerNo
Show full input schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "participants",
    "date_from",
    "date_to",
    "duration_minutes"
  ],
  "properties": {
    "participants": {
      "type": "array",
      "minItems": 2,
      "maxItems": 12,
      "description": "People or teams with their own zone and hours.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "timezone"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 60
          },
          "timezone": {
            "type": "string",
            "maxLength": 64,
            "description": "IANA zone."
          },
          "work_start": {
            "type": "string",
            "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
            "default": "09:00"
          },
          "work_end": {
            "type": "string",
            "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
            "default": "17:00"
          },
          "work_days": {
            "type": "array",
            "minItems": 1,
            "maxItems": 7,
            "uniqueItems": true,
            "items": {
              "type": "integer",
              "minimum": 1,
              "maximum": 7
            },
            "description": "ISO weekdays (default 1-5)."
          }
        }
      }
    },
    "date_from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First day of the search window (in window_timezone)."
    },
    "date_to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last day of the search window (inclusive)."
    },
    "window_timezone": {
      "type": "string",
      "maxLength": 64,
      "default": "UTC"
    },
    "duration_minutes": {
      "type": "integer",
      "minimum": 15,
      "maximum": 480
    },
    "step_minutes": {
      "type": "integer",
      "enum": [
        15,
        30,
        60
      ],
      "default": 30
    },
    "unsocial_start": {
      "type": "string",
      "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
      "default": "22:00",
      "description": "Local time from which hours count as unsocial."
    },
    "unsocial_end": {
      "type": "string",
      "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
      "default": "07:00",
      "description": "Local time until which hours count as unsocial."
    },
    "allow_unsocial": {
      "type": "boolean",
      "default": false
    },
    "rotation": {
      "type": "integer",
      "minimum": 1,
      "maximum": 12,
      "default": 1,
      "description": "Number of different slots to rotate a recurring meeting through."
    },
    "max_results": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 10
    }
  }
}

Open original schema

Published input example

{
  "participants": [
    {
      "name": "Berlin",
      "timezone": "Europe/Berlin"
    },
    {
      "name": "New York",
      "timezone": "America/New_York"
    }
  ],
  "date_from": "2026-11-17",
  "date_to": "2026-11-17",
  "duration_minutes": 60
}

Result & documentation

Machine-readable documentation of this hub

Source of this page: the published HALOWERK catalog. Updated: 2026-11-17 UTC.

More endpoints in this hub

All endpoints in this hub โ†’