Time of Meeting

Propose up to three fair meeting times while the slot is still being chosen. Ranking does not take a meeting length. Each slot has a score and the reasons. The result has one https://timeofmeeting.com link that opens the planner with those cities, and next_step, which says the user can choose a duration when creating the invitation. It does not include calendar files or a QR code. After a slot is chosen, call create_meeting_link.

{
  "type": "object",
  "properties": {
    "cities": {
      "description": "Two to eight cities. An array, or one comma-separated string. City name or a city id from search_cities. Spelling and accents are flexible.",
      "type": "array",
      "minItems": 2,
      "maxItems": 8,
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 80
      }
    },
    "start_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First day, YYYY-MM-DD. Defaults to today (UTC)."
    },
    "end_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last day, YYYY-MM-DD. Defaults to six days after the start. At most 31 days."
    }
  },
  "required": [
    "cities"
  ]
}

Convert one city's local time into one or more other cities. The result includes a https://timeofmeeting.com link for a 60-minute meeting. Choose a different length with create_meeting_link.

{
  "type": "object",
  "properties": {
    "from": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "The city the clock time belongs to. City name or a city id from search_cities. Spelling and accents are flexible."
    },
    "to": {
      "description": "Cities to convert into. An array, or one comma-separated string. City name or a city id from search_cities. Spelling and accents are flexible.",
      "type": "array",
      "minItems": 1,
      "maxItems": 7,
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 80
      }
    },
    "time": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}[T ]\\d{2}:\\d{2}$",
      "description": "Local time in the from city, YYYY-MM-DD HH:MM or YYYY-MM-DDTHH:MM."
    }
  },
  "required": [
    "from",
    "to",
    "time"
  ]
}

Show the current local time, offset, and work-hour band for each city. The result includes a https://timeofmeeting.com link.

{
  "type": "object",
  "properties": {
    "cities": {
      "description": "One to eight cities. An array, or one comma-separated string. City name or a city id from search_cities. Spelling and accents are flexible.",
      "type": "array",
      "minItems": 1,
      "maxItems": 8,
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 80
      }
    }
  },
  "required": [
    "cities"
  ]
}

Find cities by name. Each city includes its id, time zone, country, and a https://timeofmeeting.com link.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "City name, such as Bern or Zürich. Spelling and accents are flexible. A city id such as gn:2657896 is also accepted."
    }
  },
  "required": [
    "query"
  ]
}

List clock changes for one city. Defaults to the next year. Each change includes a https://timeofmeeting.com link. The range can be at most 366 days.

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "City name or a city id from search_cities. Spelling and accents are flexible."
    },
    "start_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First day, YYYY-MM-DD. Defaults to today (UTC)."
    },
    "end_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last day, YYYY-MM-DD. Defaults to 365 days later."
    }
  },
  "required": [
    "city"
  ]
}

Build the invitation for one chosen slot. duration_minutes is the meeting length, chosen now, with the same choices as the planner Duration control. title is an optional meeting name, e.g. Weekly sync. The first item is always the planner link: open this meeting on timeofmeeting.com (see and adjust it in the planner). formats then adds text to paste into a chat or email, a calendar file for Outlook, Apple Calendar and most calendar apps, an add-to-Google-Calendar link, or a QR code image someone can scan with a phone, in that order. Use this after find_best_meeting_time, or when the time is already known.

{
  "type": "object",
  "properties": {
    "cities": {
      "description": "Two to eight cities. An array, or one comma-separated string. City name or a city id from search_cities. Spelling and accents are flexible.",
      "type": "array",
      "minItems": 2,
      "maxItems": 8,
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 80
      }
    },
    "start": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}[T ]\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:\\d{2})?$",
      "description": "ISO time with Z or an offset, or a local time in the first city (YYYY-MM-DD HH:MM)."
    },
    "title": {
      "type": "string",
      "maxLength": 100,
      "description": "Optional meeting name, e.g. Weekly sync. It is the calendar event name and the first line of the text. When omitted, the invitation stays as it is now."
    },
    "duration_minutes": {
      "type": "integer",
      "minimum": 5,
      "maximum": 1440,
      "multipleOf": 5,
      "default": 30,
      "description": "Meeting length in minutes, chosen when the invitation is made. Same choices as the planner Duration control: 15, 30, 45, 60, 90, 120, or any whole number from 5 to 1440 in steps of 5. Default 30."
    },
    "formats": {
      "type": "array",
      "uniqueItems": true,
      "items": {
        "oneOf": [
          {
            "const": "text",
            "description": "text to paste into a chat or email"
          },
          {
            "const": "ics",
            "description": "calendar file for Outlook, Apple Calendar and most calendar apps"
          },
          {
            "const": "google",
            "description": "add-to-Google-Calendar link"
          },
          {
            "const": "qr",
            "description": "QR code image someone can scan with a phone"
          }
        ]
      },
      "description": "Extras after the planner link, which is always included: open this meeting on timeofmeeting.com (see and adjust it in the planner). Returned in this order: text (text to paste into a chat or email), ics (calendar file for Outlook, Apple Calendar and most calendar apps), google (add-to-Google-Calendar link), qr (QR code image someone can scan with a phone). Default when omitted: [\"text\", \"ics\", \"google\"]. An empty array returns the planner link only. qr is included only when requested."
    }
  },
  "required": [
    "cities",
    "start"
  ]
}