Overview

Seamlessly integrate your event planning with T.io and receive real-time, weather-specific insights and notifications tailored to the right recipients at the right time. By aligning your events with precise weather forecasts, you can plan more efficiently, minimize disruptions, and optimize operations based on weather conditions.

This API allows you to create or update event details from your internal system on the Tomorrow.io platform, connecting them to predefined alerts. These alerts are triggered only during the event's timeframe, ensuring timely and relevant notifications.

Synced events can be visualized on the platform's insights dashboard, allowing you to assess potential risks in advance by viewing weather insights in the context of your events.

Relevant Endpoints:

Sync Event Endpoint

https://api.tomorrow.io/v4/sync-event

Request Body Parameters

Parameter Name	Data Type	Description	Sample Value	Required	Validations
externalId	string	The external ID of the event. This id is used to identify the event and decide if this is a create or an update operation.	"67890"	Yes
name	string	The name of the event	"Test"	Yes
startTime	string	Start date and time of the event in ISO 8601 format	"2024-07-18T10:00:00Z"	Yes
endTime	string	End date and time of the event in ISO 8601 format	"2024-07-18T12:00:00Z"	Yes	Must be after startTime
location	object	The location of the event. The endpoint supports finding event by id or name. If not found, geometry details can be provided and a location will be created and linked to the event.	{"id":"6593f162212b18a3b182f23b" }	Yes	Each location must have location id or name and GeoJSON geometry (point, polygon, polyline) in case the location does not exist.
groups	array of strings	The group names that will be subscribed to the event.		No	The groups must exist in the platform before linking them to the event. Max 50 groups in the array.
users	array of strings	The user emails that will be subscribed to the event.		No	Max 50 users in the array.
eventTags	array of strings	Tags associated with the event. The tags will be set to the event and are shown in the platform UI.		No	Max 50 tags in the array.
alertTags	array of strings	Alert tags associated with the event. The alerts tags is one way to link alerts to the event. Any alert with the specified tag will be linked to the event.		No	Max 50 tags in the array.
alertIds	array of strings	The alert ids for which the event will be linked to.		No	The alerts must exist in the platform before linking them to the event. Max 50 alerts in the array.
persistLocation	boolean	Configuration of whether to persist the location. By default, location that doesn't exists and received in the request will be created and deleted once the event is over. Setting this parameter to ‘True’ will result in not deleting the location when the event is over. If the use case is for temporary locations it is advised to set this to false so the locations quotas won't be exceeded.	false	No

Request Example

Example 1 (existing location):

{
    "externalId": "67890",
    "name": "Test event 2",
  	"startTime": "2024-08-02T11:00:00.571Z",
  	"endTime": "2024-08-02T16:00:00.482Z",
    "location": {
      "id":"6593f162212b18a3b182f23b"
    },
    "groups": [
      	"group1",
      	"group2"
    ],
    "users": [
      	"[email protected]", 
      	"[email protected]"
    ],
    "eventTags": [
    	"Public Events",
    	"Free Events"
  	],
    "alertTags": [
    	"Public Events",
    	"Free Events"
  	]
}

Example 2 (location doesn’t exist):

{
    "externalId": "test-event-1",
    "name": "Test event 1",
    "startTime": "2020-01-01T00:00:00Z",
    "endTime": "2020-01-01T01:00:00Z",
    "location": {
        "name": "Keith Howe",
        "geometry": {
            "type": "Polygon",
            "coordinates": [
              [
                [-122.47736940728976, 45.155939],
                [-122.47758235998081, 45.16271526450315],
                [-122.478220377627, 45.16946478618608],
                [-122.47736940728976, 45.155939]
              ]
            ]
          }
        },
    "groups": ["group1","group2"],
    "users": ["[email protected]", "[email protected]"],
    "eventTags": ["tag1", "tag2"],
    "alertIds": [
    	"bd223359-f90c-4b11-8168-9a0305bdc085"
  	]
    "persistLocation": true
}

Response Example

{
    "data": {
      "event": {
        	"id": "0048bbb7-8398-4a09-b6de-c60693609596",
        	"name": "Test event 1",
        	"externalId": "test-event-1",
          "startTime": "2020-01-01T00:00:00.000Z",
          "endTime": "2020-01-01T01:00:00.000Z",
          "locationId": "664a0d128d24f65f1eed3471",
          "createdAt": "2024-05-20T14:03:05.455Z",
          "updatedAt": "2024-05-20T14:03:05.455Z",
          "createdBy": "60b36e15bf65330008214556",
          "updatedBy": "60b36e15bf65330008214556",
          "users": [
            "[email protected]",
            "[email protected]"
          ],
          "groups": [
            "group1"
          ]
        }
    }
}

Delete Event Endpoint

https://api.tomorrow.io/v4/calendar-events/{eventId}

Request Path Parameters

Parameter Name	Data Type	Description	Sample Value	Required	Validations
eventId	string	Tomorrow.io ID of the event to be deleted.	"67890"	Yes

Integration Details

To integrate your data you need to have an authorized API key. Please reach out to your account manager to receive the authentication information and any additional integration details.