We have created new APIs that you can use to create dashboard API Actions. These APIs simplify working across different time zones and help you prepare for upcoming or past events. All Forethought customers can access these APIs.
Authentication
To access our APIs, reach out to your Customer Success Manager to get the API key. This key must be included in the request header as X-API-KEY. Make sure the key matches the one linked to your Solve widget; otherwise, you’ll receive a 401 Unauthorized error.
API Endpoints
1. Get Current Time
Endpoint
GET https://api.forethought.ai/time/currentDescription
This endpoint provides the current time object for any time zone you specify, no need to guess or manually calculate time differences. This endpoint keeps you updated with real-time data across regions.
Request Parameters
| Name | Type | Required | Description |
| timezone | string | true | A valid timezone string, such as "America/Los_Angeles". |
Example request
GET /time/current?timezone=America/New_York
X-API-KEY: your_api_key_hereExample response
{
"timezone": "Europe/Amsterdam",
"year": 2021,
"month": 11,
"day": 26,
"hour": 2,
"minutes": 45,
"seconds": 0,
"milli_seconds": 0,
"date_time": "2021-11-26T02:45:00+01:00",
"date": "11/26/2021",
"time": "02:45:00",
"day_of_week": "Friday",
"formatted_date_time": "2021-11-26 02:45:00"
}2. Time Calculation (Increment or Decrement)
Endpoint
POST https://api.forethought.ai/time/calculationDescription
This endpoint allows you to adjust the time forward or backward by a specified amount, whether that’s in hours, minutes, or days. Simply indicate how much you want to change the time and in which direction, and it will return a new time object based on your input.
Request Parameters
| Name | Type | Required | Description |
| timezone | string | true | A valid IANA timezone string, such as "America/Los_Angeles". |
| time_span | string | true | The time span in the format "dd:hh:mm:ss" representing days, hours, minutes, and seconds to adjust the custom date-time. |
| custom_date_time | string | true | The custom date-time in the format "YYYY-MM-DD HH:MM:SS" on which the calculation will be performed. |
| operation | string | true | Operation type (increment or decrement) indicating whether to add or subtract the specified time span. |
Example request
POST /time/calculation
X-API-KEY: your_api_key_here
{
"timezone": "Europe/Amsterdam",
"custom_date_time": "2021-11-27 05:45:00",
"time_span": "01:03:00:00",
"operation":"decrement"
}
Example response
{
"original_date_time": "2021-11-27T05:45:00+01:00",
"time_span": "01:03:00:00",
"result": {
"timezone": "Europe/Amsterdam",
"year": 2021,
"month": 11,
"day": 26,
"hour": 2,
"minutes": 45,
"seconds": 0,
"milli_seconds": 0,
"date_time": "2021-11-26T02:45:00+01:00",
"date": "11/26/2021",
"time": "02:45:00",
"day_of_week": "Friday",
"formatted_date_time": "2021-11-26 02:45:00"
}
}3. Transform timestamp to date time object
Endpoint
GET https://api.forethought.ai/time/to-datetime/{timestamp}Description
Takes a timestamp as input and returns the corresponding date time object.
Request Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| timestamp | string | true | The timestamp you will want to transform |
Example request
GET /time/to-datetime/1678538400
X-API-KEY: your_api_key_hereExample response
{
"timezone": "UTC",
"year": 2023,
"month": 3,
"day": 11,
"hour": 12,
"minutes": 40,
"seconds": 0,
"milli_seconds": 0,
"date_time": "2023-03-11T12:40:00",
"date": "03/11/2023",
"time": "12:40:00",
"day_of_week": "Saturday",
"formatted_date_time": "March 11, 2023, 12:40:00 PM",
"unix_timestamp": 1678567200,
"iso_standard_date_time":"2021-11-26 02:45:00"
"is_weekday":True
}4. Get next weekday
Endpoint
POST https://api.forethought.ai/time/next-weekday-date Description
Get the next weekday date object
Request Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| timezone | string | true |
A valid IANA timezone string, such as "America/Los_Angeles".
|
Example request
POST /time/next-weekday-date
X-API-KEY: your_api_key_here
{
"timezone": "Europe/Amsterdam",
"date_time": "2021-11-27 05:45:00",
}Example response
{
"timezone": "Europe/Amsterdam",
"year": 2021,
"month": 11,
"day": 29,
"hour": 5,
"minutes": 45,
"seconds": 0,
"milli_seconds": 0,
"date_time": "2021-11-29T05:45:00",
"date": "11/29/2021",
"time": "05:45:00",
"day_of_week": "Monday",
"formatted_date_time": "November 29, 2021, 05:45:00 AM",
"unix_timestamp": 1638193500,
"iso_standard_date_time": "2021-11-29 05:45:00",
"is_weekday": true
}5. Date difference
Endpoint
POST https://api.forethought.ai/time/date-differenceDescription
Calculates the absolute time difference between two dates, returning the result broken down into days, hours, minutes, and seconds.
Request Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| start_date | string | true |
The start date in the format "YYYY-MM-DD HH:MM:SS"
|
| end_date | string | true |
The end date in the format "YYYY-MM-DD HH:MM:SS"
|
Example request
POST /time/date-difference
X-API-KEY: your_api_key_here
{
"end_date":"2024-11-06 14:30:01",
"start_date":"2024-11-08 16:45:00"
}Example response
{
"total_days_difference": 2,
"remaining_hours": 2,
"remaining_minutes": 14,
"remaining_seconds": 59
}Note: The calculation is absolute. The API will always return a positive time difference, regardless of the order of the input dates.
Comments
Article is closed for comments.