Commit 12a1ee8

---

kind: change

title: Improved timezone handling in the API

created_at: 2014-02-27

author_name: dbussink

---

Timezones always present interesting engineering problems. Git already handles

this by allowing for timezone offset information in for example commits. We have

improved support in our API as well. If you create commits through the API, we

now allow for specifying timezone information more accurately.

We use the following steps to determine the timezone we use when a timestamp is

generated in the API. These steps are ordered by priority, so we use the first

case in this list that applies to the call you make.

#### Explicitly provide an ISO 8601 timestamp with timezone information

For API call that allows for a timestamp to be specified, we use that exact

timestamp. An example of this is the [Commits API](v3/git/commits).

These timestamps look something like `2014-02-27T15:05:06+01:00`

#### Using the `Time-Zone` header

It is possible to supply a `Time-Zone` header which defines a timezone according

to the [list of names from the Olson database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).

This means that we generate a timestamp for the moment your API call is made in

the timezone this header defines. For example the [Contents API](v3/repos/contents/)

generates a git commit for each addition or change and uses the current time

as the timestamp. This header will determine the time zone used for generating

that current timestamp.

#### Using the last known timezone for the user

If no `Time-Zone` header is specified and you make an authenticated call to the

API, we use the last known timezone for the authenticated user. The last know

timezone is updated whenever you browse the GitHub.com website.

#### UTC

If the steps above don't result in any information, we use UTC as the timezone

to create the git commit.

[contact]: https://github.com/contact?form[subject]=API+timezones