1

Looking at the docs there is a descrepancy between the data in a checkin object for the query API s the push API with regards to timeZone.

According to https://developer.foursquare.com/overview/realtime a sample push will contain the name of the tz eg America/New_York

However according to https://developer.foursquare.com/docs/responses/checkin (and the API explorer) a checkin object will contain the timeZone offset eg 60 for GMT+1

I havn't managed to confirm whats in the Push API myself yet as I hav to setup the SSL certs, can anyone confirm of the docs are correct and we do indeed have 2 type of tz format. I would have thought that including the timeZone rather than the offset would be better as this doesn't vary with Daylight Savings unlike the figure. Europe/London will always be a constant where as the offset will switch between 0 and 60 mins

Sam Machin
  • 3,063
  • 5
  • 20
  • 18

2 Answers2

0

I'm not directly familiar with FourSquare's API, so I can't confirm or deny this for you. But I can tell you there are often cases where you would use both.

It is ok to only present an offset, if the data represents a particular time. Since the checkin response provides a createdAt date/time as an integer seconds since epoch (aka a "Unix Timestamp"), then it is appropriate to provide a separate offset. (Although I find it interesting that they provide the offset as a string and not as an integer number of minutes.) The other way you might do this would be with a single DateTimeOffset values, usually presented in ISO8601 format, as in 2013-06-02T01:23:45-07:00. Either are acceptable.

But as you may be aware, an offset does not uniquely identify a time zone. In the case of a single event, it doesn't need to. But if it were a recurring event, or if there was a possibility that you might want to modify the time value, then an offset alone would not suffice. That's when you need the full zone identifier.

If you have a zone identifier such as America/New_York, then you can always find out what the correct offset for any date/time would be. But not everyone has a TZDB implementation readily available. For example, in .Net on Windows, you get Microsoft's clumsy time zone database by default, and you have to find a library (like NodaTime) if you want to use the TZDB zones.

It does seem strange that the push and pull for the same type of action (a check-in) would have different values just because they were going through different APIs. My advice (to Foursquare) would be threefold:

  • Be consistent about the data for the same activity, regardless of push vs pull.
  • Provide both the TZDB identifier, and the the UTC offset associated with the event.
  • Provide the event's timestamp and offset in a single value, as an ISO8601 formatted string, rather than a unix time integer.
Matt Johnson-Pint
  • 230,703
  • 74
  • 448
  • 575
0

The Foursquare documentation is correct but a bit incomplete (as of time of posting). The check-in response contains a timeZoneOffset field. The real-time push response has a timeZone field and a timeZoneOffset field—the timeZone field is still there for legacy purposes.

Thanks for pointing this out; we'll update the docs to reflect that timeZoneOffset is the preferred method at this point. As Matt mentioned, the offset method is a better way to identify a particular time from createdAt.

octopi
  • 2,004
  • 1
  • 12
  • 16