Skip to content

Commit 0bc4ce2

Browse files
committed
Add timezone handling list to general docs as well
1 parent 86036ef commit 0bc4ce2

1 file changed

Lines changed: 39 additions & 0 deletions

File tree

content/v3.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -571,5 +571,44 @@ A link that looks like this:
571571
["url1", {:rel => "next"}],
572572
["url2", {:rel => "foo", :bar => "baz"}]] %>
573573

574+
## Timezones
575+
576+
Some requests allow for specifying timestamps or generate timestamps with time
577+
zone information. We apply the following rules, in order of priority, to
578+
determine timezone information for API calls.
579+
580+
#### Explicitly provide an ISO 8601 timestamp with timezone information
581+
582+
For API calls that allow for a timestamp to be specified, we use that exact
583+
timestamp. An example of this is the [Commits API](/v3/git/commits).
584+
585+
These timestamps look something like `2014-02-27T15:05:06+01:00`. Also see
586+
[this example](http://developer.github.com/v3/git/commits/#example-input) for
587+
how these timestamps can be specified.
588+
589+
#### Using the `Time-Zone` header
590+
591+
It is possible to supply a `Time-Zone` header which defines a timezone according
592+
to the [list of names from the Olson database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
593+
594+
$ curl -H "Time-Zone: Europe/Amsterdam" -X POST https://api.github.com/repos/github/linguist/contents/new_file.md
595+
596+
This means that we generate a timestamp for the moment your API call is made in
597+
the timezone this header defines. For example the [Contents API](/v3/repos/contents/)
598+
generates a git commit for each addition or change and uses the current time
599+
as the timestamp. This header will determine the time zone used for generating
600+
that current timestamp.
601+
602+
#### Using the last known timezone for the user
603+
604+
If no `Time-Zone` header is specified and you make an authenticated call to the
605+
API, we use the last known timezone for the authenticated user. The last know
606+
timezone is updated whenever you browse the GitHub.com website.
607+
608+
#### UTC
609+
610+
If the steps above don't result in any information, we use UTC as the timezone
611+
to create the git commit.
612+
574613
[support]: https://github.com/contact?form[subject]=APIv3
575614
[pagination-guide]: /guides/traversing-with-pagination

0 commit comments

Comments
 (0)