๐Ÿ•’ Date and Timezone Management in Our API

Introduction

This documentation aims to guide you in handling dates and timezones when using our API. We will explain why we have chosen to use the ISO 8601 format in UTC for dates, how to retrieve the school's timezone, and how to convert dates according to your application's needs. We will also provide resources and tools to facilitate these conversions.

Date Format in the API

Using ISO 8601 Format in UTC

For resources such as courses, our API returns the start and end dates in ISO 8601 format in Coordinated Universal Time (UTC). For example:

"START": "2023-10-23T14:00:00Z",
"END": "2023-10-23T16:00:00Z"

Why This Choice?

  • Standardization: The ISO 8601 format is an international standard for date and time representation, facilitating interoperability between different systems and applications.
  • Avoiding Ambiguities: By using UTC, we prevent issues related to timezones, such as time shifts and daylight saving time changes.
  • Simplicity: This allows developers to start from a single time reference and convert it based on the specific needs of the end-user.

Reference Resource

For more information on the ISO 8601 format, you can consult the following article: ISO 8601 on Wikipedia.

Retrieving the School's Timezone

Our API provides a specific route to retrieve the timezone associated with a school. This information is essential for converting UTC dates to local time.

Example Request

GET /v1/school

Response

{
 ...,
  "TIMEZONE": "America/Mexico_City"
}

Converting Dates to Local Time

Once you have the date in UTC and the school's timezone, you can convert the date to local time in your application.

Conversion Tools by Programming Language

JavaScript

  • Date Object: The native Date object can be used for basic conversions.
  • Libraries:

Python

  • datetime: The datetime module with the timezone class to handle timezones.
  • pytz: A library that provides comprehensive timezone support.
  • Pendulum: An intuitive alternative to datetime and pytz.

Java

  • java.time: The java.time package (Java 8 and above) includes ZonedDateTime and ZoneId.
  • Joda-Time: For earlier versions of Java or additional features.

PHP

  • DateTime: The DateTime class with DateTimeZone to handle timezones.
  • Carbon: An extension of DateTime offering a more user-friendly syntax.

Using the Timezone Conversion API

If you prefer a ready-to-use solution, you can utilize the following API for conversions:

Usage Example

POST https://timeapi.io/api/conversion/converttimezone

Body

{  
  "fromTimeZone": "UTC",  
  "dateTime": "2023-10-23 14:00:00",  
  "toTimeZone": "America/Mexico_City",  
  "dstAmbiguity": ""  
}

Response

{
  "fromTimeZone": "UTC",
  "toTimeZone": "America/Mexico_City",
  "originalDateTime": "2023-10-23T14:00:00",
  "convertedDateTime": "2023-10-23T09:00:00"
}

Conclusion

Proper management of dates and timezones is crucial to ensure a consistent user experience. By using the ISO 8601 format in UTC and providing the school's timezone, our API gives you the necessary tools to effectively handle dates in your applications. Feel free to use the mentioned libraries or the conversion API to adapt dates to your specific needs.