Time API: Documentation

Get Started with the Time API

Get the current time for any location on Earth and changes in Daylight Saving Times; and convert time zones – with a few lines of code in your language of choice.

Install Official Libraries

To get started, use one of timeanddate.com's official API libraries for your programming language. If your language isn't supported, you can send the requests manually over HTTP. If you would like to request an official library for your language, please contact us.


    $ dotnet add package TimeAndDate.Services
                

Build Query

The API library is now installed. Next, you specify the location for which you want to query the current time, and whether or not to include additional information like the list of time changes for the current year, and time zone information like UTC offset. You can find all available locations in our location overview. If you are using our Premium Package, you can query for langitude and latitude instead.

To perform the query, you will need your access key and secret key: Get them from the Access Key page on My Account. Don't have a key? Sign up for our free trial and receive an access key to try it out.


    var place = new LocationId("norway/oslo");
    var service = new TimeService('accessKey', 'secretKey');
    service.IncludeListOfTimeChanges = true;
    service.IncldueTimezoneInformation = true;
                    

Get Result

The result variable will now contain the the current time for the specified location, as well as time zone information, and time changes for the current year.


    var result = service.GetCurrentTimeForPlace(place);
                    

Where to go next?

See our GitHub repository for more information on the C#/.NET Library.


    <repository>
        <id>github</id>
        <name>Time and Date API Packages</name>
        <url>https://maven.pkg.github.com/timeanddate/libtad-jvm</url>
    </repository>
    <dependency>
        <groupId>com.timeanddate</groupId>
        <artifactId>services</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </dependency>
                    

Build Query

The API library is now installed. Next, you specify the location for which you want to query the current time, and whether or not to include additional information like the list of time changes for the current year, and time zone information like UTC offset. You can find all available locations in our location overview. If you are using our Premium Package, you can query for langitude and latitude instead.

To perform the query, you will need your access key and secret key: Get them from the Access Key page on My Account. Don't have a key? Sign up for our free trial and receive an access key to try it out.


    LocationId place = new LocationId("norway/oslo");
    TimeService service = new TimeService('accessKey', 'secretKey');
    service.setIncludeListOfTimeChanges(true);
    service.setIncldueTimezoneInformation(true);
                    

Get Result

The result variable will now contain the the current time for the specified location, as well as time zone information, and time changes for the current year.


    List<Location> result = service.getCurrentTimeForPlace(place);
                    

Where to go next?

See our GitHub repository for more information on the Java/JVM Library.


    # Carthage
    github "TimeAndDate/TadApi"
    # CocoaPods
    pod 'libtad-swift', '~> 1.0'
                    

Build Query

The API library is now installed. Next, you specify the location for which you want to query the current time, and whether or not to include additional information like the list of time changes for the current year, and time zone information like UTC offset. You can find all available locations in our location overview. If you are using our Premium Package, you can query for langitude and latitude instead.

To perform the query, you will need your access key and secret key: Get them from the Access Key page on My Account. Don't have a key? Sign up for our free trial and receive an access key to try it out.


    let service = TimeService(accessKey: accessKey, secretKey: secretKey)
    let request = TimeRequest()
    request.placeId = "norway/oslo"
    request.timechanges = true
    request.tz = true
                    

Get Result

The result variable will now contain the the current time for the specified location, as well as time zone information, and time changes for the current year.


    service.getCurrentTime(request: request, completionHandler: { (result, error) in
        print(result)
    }
                    

Where to go next?

See our GitHub repository for more information on the Swift Library.

Build Query

You will need cURL installed in order to execute the following commands. The following samples also require you to have enabled "Insecure Methods" on your access key.


$ ACCESSKEY="<Your Access Key>"
$ SECRETKEY="<Your Secret Key>"
$ curl -G \
    --data-urlencode "version=3" \
    --data-urlencode "prettyprint=1" \
    --data-urlencode "accesskey=$ACCESSKEY" \
    --data-urlencode "secretkey=$SECRETKEY" \
    --data-urlencode "placeid=norway/oslo" \
    https://api.xmltime.com/timeservice
    

Get Result

Execute cURL with the parameters set previously and receive the resulting calculation as a JSON object.


    {
      "version": 3,
      "billing": {
        "credits": 1
      },
      "locations": [
        {
          "id": "187",
          "geo": {
            "name": "Oslo",
            "country": {
              "id": "no",
              "name": "Norway"
            },
            "latitude": 59.913,
            "longitude": 10.740
          },
          "time": {
            "iso": "2021-02-05T14:17:07+01:00",
            "datetime": {
              "year": 2021,
              "month": 2,
              "day": 5,
              "hour": 14,
              "minute": 17,
              "second": 7
            },
            "timezone": {
              "offset": "+01:00",
              "zoneabb": "CET",
              "zonename": "Central European Time",
              "zoneoffset": 3600,
              "zonedst": 0,
              "zonetotaloffset": 3600
            }
          },
          "timechanges": [
            {
              "newdst": 3600,
              "newzone": null,
              "newoffset": 7200,
              "utctime": "2021-03-28T01:00:00",
              "oldlocaltime": "2021-03-28T02:00:00",
              "newlocaltime": "2021-03-28T03:00:00",
              "verbose": {
                "utctime": {
                  "datetime": {
                    "year": 2021,
                    "month": 3,
                    "day": 28,
                    "hour": 1,
                    "minute": 0,
                    "second": 0
                  }
                },
                "oldlocaltime": {
                  "datetime": {
                    "year": 2021,
                    "month": 3,
                    "day": 28,
                    "hour": 2,
                    "minute": 0,
                    "second": 0
                  }
                },
                "newlocaltime": {
                  "datetime": {
                    "year": 2021,
                    "month": 3,
                    "day": 28,
                    "hour": 3,
                    "minute": 0,
                    "second": 0
                  }
                }
              }
            },
            {
              "newdst": 0,
              "newzone": null,
              "newoffset": 3600,
              "utctime": "2021-10-31T01:00:00",
              "oldlocaltime": "2021-10-31T03:00:00",
              "newlocaltime": "2021-10-31T02:00:00",
              "verbose": {
                "utctime": {
                  "datetime": {
                    "year": 2021,
                    "month": 10,
                    "day": 31,
                    "hour": 1,
                    "minute": 0,
                    "second": 0
                  }
                },
                "oldlocaltime": {
                  "datetime": {
                    "year": 2021,
                    "month": 10,
                    "day": 31,
                    "hour": 3,
                    "minute": 0,
                    "second": 0
                  }
                },
                "newlocaltime": {
                  "datetime": {
                    "year": 2021,
                    "month": 10,
                    "day": 31,
                    "hour": 2,
                    "minute": 0,
                    "second": 0
                  }
                }
              }
            }
          ],
          "astronomy": {
            "objects": [
              {
                "name": "sun",
                "events": [
                  {
                    "type": "rise",
                    "hour": 8,
                    "minute": 20
                  },
                  {
                    "type": "set",
                    "hour": 16,
                    "minute": 42
                  }
                ]
              }
            ]
          },
          "matchparam": "187"
        }
      ]
    }
                    

Install Official Libraries

To get started, use one of timeanddate.com's official API libraries for your programming language. If your language isn't supported, you can send the requests manually over HTTP. If you would like to request an official library for your language, please contact us.


    $ dotnet add package TimeAndDate.Services
                    

Build Query

The API library is now installed. Next, you specify the location you want to query from (target), and the location you want to convert time to (destination). Find all available locations in our location overview. Users of our Premium Package can also query for longitude and latitude.

To perform the query, you will need your access key and secret key: Get them from the Access Key page on My Account. Don't have a key? Sign up for our free trial and receive an access key to try it out.


    var listOfLocations = new List<LocationId>();
    listOfLocations.Add(new LocationId("usa/las-vegas"));
    listOfLocations.Add(new LocationId(179);
    
    var place = new LocationId("oslo/norway");
    var service = new ConvertTimeService('accessKey', 'secretKey');
                    

Get Result

The result variable will now contain the the current time for the specified location, as well as the local time for the locations you wanted to convert to.


    var result = service.ConvertTime(place, DateTime.Now, listOfLocations);
                    

Where to go next?

See our GitHub repository for more information on the C#/.NET Library.


    <repository>
        <id>github</id>
        <name>Time and Date API Packages</name>
        <url>https://maven.pkg.github.com/timeanddate/libtad-jvm</url>
    </repository>
    <dependency>
        <groupId>com.timeanddate</groupId>
        <artifactId>services</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </dependency>
                    

Build Query

The API library is now installed. Next, you specify the location you want to query from (target), and the location you want to convert time to (destination). Find all available locations in our location overview. Users of our Premium Package can also query for longitude and latitude.

To perform the query, you will need your access key and secret key: Get them from the Access Key page on My Account. Don't have a key? Sign up for our free trial and receive an access key to try it out.


    List<LocationId> listOfLocations = new ArrayList<LocationId>();
    listOfLocations.add(new LocationId("usa/las-vegas"));
    listOfLocations.add(new LocationId(179);
    
    LocationId place = new LocationId("oslo/norway");
    ConvertTimeService service = new ConvertTimeService('accessKey', 'secretKey');
                    

Get Result

The result variable will now contain the the current time for the specified location, as well as the local time for the locations you wanted to convert to.


    ConvertedTimes result = service.convertTime(place, Calendar.getInstance(), listOfLocations);
                    

Where to go next?

See our GitHub repository for more information on the Java/JVM Library.


    # Carthage
    github "TimeAndDate/TadApi"
    # CocoaPods
    pod 'libtad-swift', '~> 1.0'
                    

Build Query

The API library is now installed. Next, you specify the location you want to query from (target), and the location you want to convert time to (destination). Find all available locations in our location overview. Users of our Premium Package can also query for longitude and latitude.

To perform the query, you will need your access key and secret key: Get them from the Access Key page on My Account. Don't have a key? Sign up for our free trial and receive an access key to try it out.


    let service = ConvertTimeService(accessKey: "accessKey", secretKey:"secretKey")
    let request = ConvertTimeRequest()
    request.fromPlaceId = "oslo/norway"
    request.toPlaceId = "usa/las-vegas,179"
                    

Get Result

The result variable will now contain the the current time for the specified location, as well as the local time for the locations you wanted to convert to.


    service.convertTime(request:request) { (result, error) in 
        print(result)
    }
                    

Where to go next?

See our GitHub repository for more information on the Swift Library.

Build Query

You will need cURL installed in order to execute the following commands. The following samples also require you to have enabled "Insecure Methods" on your access key.


$ ACCESSKEY="<Your Access Key>"
$ SECRETKEY="<Your Secret Key>"
$ curl -G \
    --data-urlencode "version=3" \
    --data-urlencode "prettyprint=1" \
    --data-urlencode "accesskey=$ACCESSKEY" \
    --data-urlencode "secretkey=$SECRETKEY" \
    --data-urlencode "fromid=norway/oslo" \
    --data-urlencode "toid=mozambique/maputo" \
    --data-urlencode "iso=2020-11-26T09:35:12" \
    https://api.xmltime.com/converttime
                    

Get Result

Execute cURL with the parameters set previously and receive the resulting calculation as a JSON object.


    {
      "version": 3,
      "billing": {
        "credits": 1
      },
      "locations": [
        {
          "id": "187",
          "geo": {
            "name": "Oslo",
            "country": {
              "id": "no",
              "name": "Norway"
            },
            "latitude": 59.913,
            "longitude": 10.740
          },
          "time": {
            "iso": "2021-02-05T14:17:07+01:00",
            "datetime": {
              "year": 2021,
              "month": 2,
              "day": 5,
              "hour": 14,
              "minute": 17,
              "second": 7
            },
            "timezone": {
              "offset": "+01:00",
              "zoneabb": "CET",
              "zonename": "Central European Time",
              "zoneoffset": 3600,
              "zonedst": 0,
              "zonetotaloffset": 3600
            }
          },
          "timechanges": [
            {
              "newdst": 3600,
              "newzone": null,
              "newoffset": 7200,
              "utctime": "2021-03-28T01:00:00",
              "oldlocaltime": "2021-03-28T02:00:00",
              "newlocaltime": "2021-03-28T03:00:00",
              "verbose": {
                "utctime": {
                  "datetime": {
                    "year": 2021,
                    "month": 3,
                    "day": 28,
                    "hour": 1,
                    "minute": 0,
                    "second": 0
                  }
                },
                "oldlocaltime": {
                  "datetime": {
                    "year": 2021,
                    "month": 3,
                    "day": 28,
                    "hour": 2,
                    "minute": 0,
                    "second": 0
                  }
                },
                "newlocaltime": {
                  "datetime": {
                    "year": 2021,
                    "month": 3,
                    "day": 28,
                    "hour": 3,
                    "minute": 0,
                    "second": 0
                  }
                }
              }
            },
            {
              "newdst": 0,
              "newzone": null,
              "newoffset": 3600,
              "utctime": "2021-10-31T01:00:00",
              "oldlocaltime": "2021-10-31T03:00:00",
              "newlocaltime": "2021-10-31T02:00:00",
              "verbose": {
                "utctime": {
                  "datetime": {
                    "year": 2021,
                    "month": 10,
                    "day": 31,
                    "hour": 1,
                    "minute": 0,
                    "second": 0
                  }
                },
                "oldlocaltime": {
                  "datetime": {
                    "year": 2021,
                    "month": 10,
                    "day": 31,
                    "hour": 3,
                    "minute": 0,
                    "second": 0
                  }
                },
                "newlocaltime": {
                  "datetime": {
                    "year": 2021,
                    "month": 10,
                    "day": 31,
                    "hour": 2,
                    "minute": 0,
                    "second": 0
                  }
                }
              }
            }
          ],
          "astronomy": {
            "objects": [
              {
                "name": "sun",
                "events": [
                  {
                    "type": "rise",
                    "hour": 8,
                    "minute": 20
                  },
                  {
                    "type": "set",
                    "hour": 16,
                    "minute": 42
                  }
                ]
              }
            ]
          },
          "matchparam": "187"
        }
      ]
    }
                    

Install Official Libraries

To get started, use one of timeanddate.com's official API libraries for your programming language. If your language isn't supported, you can send the requests manually over HTTP. If you would like to request an official library for your language, please contact us.


    $ dotnet add package TimeAndDate.Services
                    

Build Query

The API library is now installed. Next, you specify the country and the year you want to query changes in Daylight Saving Time for. Alternatively, you can just list the year and get all countries with time changes in that year.

To perform the query, you will need your access key and secret key: Get them from the Access Key page on My Account. Don't have a key? Sign up for our free trial and receive an access key to try it out.


    var service = new DSTService('accessKey', 'secretKey');
    // Optional: Add TimeChanges to each location
    service.IncludeTimeChanges = true;
    // Optional: Return only countries which have DST
    service.IncludeOnlyDstCountries = true;
    // Optional: Add locations for every country
    service.IncludePlacesForEveryCountry = true;
                    

Get Result

The result variable will now contain an array of the Daylight Saving Times for the country specified, or for all countries if queried for just a given year, as well as other optional information included in the query.


    // Get Daylight Saving Times for Norway, 2020
    var result = service.GetDaylightSavingTime("no", 2020);
    // Get Worldwide Daylight Saving Times for 2020
    var result = service.GetDaylightSavingTime(2020);
    // Get Worldwide Daylight Saving Times for Norway in current year
    var result = service.GetDaylightSavingTime("no");
                    

Where to go next?

See our GitHub repository for more information on the C#/.NET Library.


    <repository>
        <id>github</id>
        <name>Time and Date API Packages</name>
        <url>https://maven.pkg.github.com/timeanddate/libtad-jvm</url>
    </repository>
    <dependency>
        <groupId>com.timeanddate</groupId>
        <artifactId>services</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </dependency>
                    

Build Query

The API library is now installed. Next, you specify the country and the year you want to query changes in Daylight Saving Time for. Alternatively, you can just list the year and get all countries with time changes in that year.

To perform the query, you will need your access key and secret key: Get them from the Access Key page on My Account. Don't have a key? Sign up for our free trial and receive an access key to try it out.


    DaylightSavingTimeService service = new DSTService('accessKey', 'secretKey');
    // Optional: Add TimeChanges to each location
    service.setIncludeTimeChanges(true);
    // Return only countries which have DST
    service.setIncludeOnlyDstCountries(true);
    // Add locations for every country
    service.setIncludePlacesForEveryCountry(true);
                    

Get Result

The result variable will now contain an array of the Daylight Saving Times for the country specified, or for all countries if queried for just a given year, as well as other optional information included in the query.


    // Get Daylight Saving Times for Norway, 2020
    List<DST> result = service.getDaylightSavingTime("no", 2020);
    // Get Worldwide Daylight Saving Times for 2020
    List<DST> result = service.getDaylightSavingTime(2020);
    // Get Daylight Saving Times for Norway in current year
    List<DST> result = service.getDaylightSavingTime("no");
                    

Where to go next?

See our GitHub repository for more information on the Java/JVM Library.


    # Carthage
    github "TimeAndDate/TadApi"
    # CocoaPods
    pod 'libtad-swift', '~> 1.0'
                    

Build Query

The API library is now installed. Next, you specify the country and the year you want to query changes in Daylight Saving Time for. Alternatively, you can just list the year and get all countries with time changes in that year.

To perform the query, you will need your access key and secret key: Get them from the Access Key page on My Account. Don't have a key? Sign up for our free trial and receive an access key to try it out.


    let service = DSTListService(accessKey: "accessKey", secretKey:"secretKey")
    let request = DSTListRequest()
    // Optional: Queries for current year if not set
    request.year = 2020
    // Optional: Queries only for Norway, else for Worldwide
    request.country = "no"
    // Optional: Add TimeChanges to each location
    request.timeChanges = true
    // Return only countries which have DST
    service.onlyDST = true
    // Add locations for every country
    service.listPlaces = true
                    

Get Result

The result variable will now contain an array of the Daylight Saving Times for the country specified, or for all countries if queried for just a given year, as well as other optional information included in the query.


    service.getDSTList(request:request) { (result, error) in 
        print(result)
    }
                    

Where to go next?

See our GitHub repository for more information on the Swift Library.

Build Query

You will need cURL installed in order to execute the following commands. The following samples also require you to have enabled "Insecure Methods" on your access key.


$ ACCESSKEY="<Your Access Key>"
$ SECRETKEY="<Your Secret Key>"
$ curl -G \
    --data-urlencode "version=3" \
    --data-urlencode "prettyprint=1" \
    --data-urlencode "accesskey=$ACCESSKEY" \
    --data-urlencode "secretkey=$SECRETKEY" \
    --data-urlencode "country=no" \
    --data-urlencode "year=2021" \
    https://api.xmltime.com/dstlist
                    

Get Result

Execute cURL with the parameters set previously and receive the resulting calculation as a JSON object.


    {
      "version": 3,
      "billing": {
        "credits": 1
      },
      "dstlist": [
        {
          "region": {
            "country": {
              "id": "no",
              "name": "Norway"
            },
            "desc": "All locations",
            "biggestplace": "Oslo"
          },
          "stdtimezone": {
            "zoneabb": "CET",
            "offset": "+01:00",
            "zonename": "Central European Time",
            "zoneoffset": 3600,
            "zonedst": 0,
            "zonetotaloffset": 3600
          },
          "dsttimezone": {
            "zoneabb": "CEST",
            "offset": "+02:00",
            "zonename": "Central European Summer Time",
            "zoneoffset": 3600,
            "zonedst": 3600,
            "zonetotaloffset": 7200
          },
          "dststart": "2021-03-28",
          "dstend": "2021-10-31"
        }
      ]
    }