General: Overview
Timeanddate.com offers several API services, including free test accounts to give you an idea of how the services work.
Timeanddate.com supplies accurate, reliable information on Local Times, Time Zones, Public holidays (days off) worldwide, Daylight Saving Time, Sunrise & Sunset times and much more. All data can be used directly in online or internal applications or imported to calendars. The services may also be combined with IP look-up (geo location) services.
Getting Started
Get started within minutes by following these steps:
Set up an account on the timeanddate.com API services page.
Choose the free trial or buy access to the services right away by choosing one of the available packages.
Create an access key on the configure access keys page and record the generated access key name and the secret key.
Request Structure
API requests are submitted by sending an HTTP or HTTPS request to a specific service URL. Request parameters are encoded in the query string. The general service URL is https://api.xmltime.com/SERVICENAME?param1=value1¶m2=value2.
Every request consists of the following 3 parts:
- Entry point: Currently, there is only one entry point available, supporting either HTTP or HTTPS connections:
https://api.xmltime.com/https://api.xmltime.com/
- Service name: The service you want to call.
- Parameters: Any parameters for the request. Please note that all parameter values have to be URL encoded. Generally, parameters are separated by using the ampersand sign (
&), but it is also accepted to use the semicolon (;) to separate parameters (see [HTML401]).
Example request:
https://api.xmltime.com/timeservice?version=3&accesskey=hs82js4vdo×tamp=2011-04-12T07%3A54%3A14%2B00%3A00&signature=4KvntdTApUC2MO6FJQqwYeVxQX0%3D&placeid=187Access Keys
Access to the timeanddate.com API services is controlled by access keys and policies. Access keys are used to authenticate the sender of the request as a valid user. In a second step, policies control access to the various services and the data which is offered. Additionally, policies can supply default values for some of the request parameters.
An access key consists of an access key id and a secret key, which are used as credentials in the authentication process. Both are randomly generated strings and cannot be changed. It is possible to create as many access keys as you need for your services. The state of the keys can be freely changed between active and inactive. If keys are no longer needed, they can be deleted. A deleted access key cannot be revived.
A policy can be assigned to each key. Assigning a policy to a key is optional – if there is no policy assigned, the default is to allow everything. We recommend to always protect your access keys with a policy that only allows features needed by your application.
Access keys can be created and managed in the timeanddate.com API services customization pages.
Key Rotation
For security reasons, keys should be changed on a regular basis (an appropriate frequency would be 90 days) – this can be done with the following steps without interrupting your service:
- Create a new access key and assign the same policy as currently assigned for the key that should be canceled. Leave the original key activated.
- Update your applications to use the new set of credentials.
- Change the state of the original access key to inactive.
- Confirm that all of your applications are still working well. If needed, you can still revert to the previous state by setting the original access key back to active.
- Delete the original access key.