Airstamp seems wrong

That's because "airstamp" contains both an airdate, airtime and timezone. So the time in airstamp is not in the show's local timezone but in the timezone specified in the string (the "+00:00" part). You should probably not try to parse airstamp yourself but use an existing datetime library that'll handle this automatically.

You can read some more at https://www.tvmaze.com/faq/15/episodes, under "airtime".

So the airstamp is UTC 0, whereas the airdate & airtime is in the Network's Timezone which in this case is UTC -4.

2012-10-11 @ 00:00 - 4 hours = 2012-10-10 @ 20:00

david wrote:
That's because "airstamp" contains both an airdate, airtime and timezone. So the time in airstamp is not in the show's local timezone but in the timezone specified in the string (the "+00:00" part). You should probably not try to parse airstamp yourself but use an existing datetime library that'll handle this automatically.

You can read some more at https://www.tvmaze.com/faq/15/episodes, under "airtime".

Would you mind explaining how one does "calculate" the airdate, airtime and timezone from that airstamp string.

Also, i'm obviously not going to parse that stamp myself and use libraries for it :)

The reason i'm asking is because i'm fairly sure it's wrong. The timezone in the stamp is UTC 0 where nothing else in the output indicates UTC -4 therefore there is no way (or i'm missing something?) to get the correct time based on the airstamp alone. In fact, there is no way at all to get the correct timezone reliably.

There is one "loose" way, but that would be a really weak and highly error prone way. It would be to count backward from whatever is the airstamp - the airtime which would give you -4 as timezone.

If you look at the show page - http://api.tvmaze.com/shows/4 - in the network there's the timezone property.

It's not ideal, as it's only the name and not the offset, but America/New_York is UTC -4.

You could try find a timezone database that you could look up the offset by name, or a library that accepts name as a parameter to date functions.

Here are some for you: PHP (native), .NET (library), javascript (library)

gazza911 wrote:
If you look at the show page - http://api.tvmaze.com/shows/4 - in the network there's the timezone property.

It's not ideal, as it's only the name and not the offset, but America/New_York is UTC -4.

You could try find a timezone database that you could look up the offset by name, or a library that accepts name as a parameter to date functions.

Here are some for you: PHP (native), .NET (library), javascript (library)

Based on that response i'm guessing it's not an option to change the API and output to just be correct?

From a technical point of view i can see why it's done as it's done. It sounds "abstract" to have 1 uniform time in all episodes and have the timezone details in the series description. But from an API user perspective this makes no sense. It is 2 API calls to get the information you want which complicates things. Yes, you can opt for the embed logic which makes it one call but that's just strange.

The output is correct though. If you can explain what you want to accomplish exactly, I'll tell you how to do it :-)

david wrote:
The output is correct though. If you can explain what you want to accomplish exactly, I'll tell you how to do it :-)

Translate the episode airtime to my local UTC (right now UTC +1, in one week UTC +2 due to daylight saving time kicking in) in node.js. Good luck :)

Well, it isn't that hard, now that i know where to get the timezone from (which i didn't before this thread).

Here's an example using moment:

https://jsfiddle.net/uojzexah/

If you want to convert to any timezone, moment-timezone-with-data.js or moment-timezone-with-data-2012-2022.js is required

If you only wanted to convert to the local timezone, then only moment.js is needed, like this:

https://jsfiddle.net/ysct3r21/

P.S moment.js will automatically work out daylight saving time

The "airstamp" property contains the episode's airtime in UTC ("+00:00"), so all you need to know is the current difference between your local timezone and UTC to make that translation. moment.js is a perfect library for that indeed.

gazza911 wrote:
Here's an example using moment:

https://jsfiddle.net/uojzexah/

If you want to convert to any timezone, moment-timezone-with-data.js or moment-timezone-with-data-2012-2022.js is required

If you only wanted to convert to the local timezone, then only moment.js is needed, like this:

https://jsfiddle.net/ysct3r21/

P.S moment.js will automatically work out daylight saving time

Nice examples! Will "fiddle" with that a bit in my application.

david wrote:
The "airstamp" property contains the episode's airtime in UTC ("+00:00"), so all you need to know is the current difference between your local timezone and UTC to make that translation. moment.js is a perfect library for that indeed.

Right, now that i know that little fact i could've used it with that assumption and would only require one request :)

Note that https://www.tvmaze.com/api makes absolutely no mention of this! The FAQ you mentioned before also makes no mention of this at all. How are we - your API users - supposed to know this little bit of quite important information? Please describe this somewhere. I'd recommend to put it on the https://www.tvmaze.com/api page as that is where devs look for information, not in the FAQ (or rarely).

Thank you both for the great help!

... i still think the output is weird though ...

It's the standard ISO 8601 format, so I don't think it's all that weird :-) But I'll give you that, extensive documentation for each attribute in the API would be useful! (But also a lot of work)

david wrote:
It's the standard ISO 8601 format, so I don't think it's all that weird :-) But I'll give you that, extensive documentation for each attribute in the API would be useful! (But also a lot of work)

Now you're confusing two different things.

I'm perfectly fine by the format if the airstamp field. It's just that it's meaning is seemingly meaningless as it is completely unknown (till one reads this thread) how one should use it as the data in that string does not correspond to the data in airdate and airtime. For me, it does now so i can make use of it :)

Having said that, now i'd kick out airdate and airtime as they can be deduced from the timestamp :)

As for the documentation. You don't have to document everything. Most fields are easy to understand with common sense. This field (airstamp) is at first sight wrong unless you know why it looks the way it looks.

Personally I find it confusing to mix UTC and local in the same api without being explicit. I would recommend either renaming airstamp to utcairstamp or making it local.

Hi again,

Sorry for reviving this now 3 years old thread. I'm still using this api and still have troubles with this very specific part. 

Let's take "The Book of Boba Fett" as an example here. When i view it's information (this call) then i see that the episodes air at "2021-12-29T12:00:00+00:00". According to information provided in this very forum thread, i should be able to just interpret that timestamp to my local time. As the timestamp should be the actual airdate in UTC-0 according to earlier information.

This is either wrong for this specific series or i'm still missing some more logic. The actual airdate of this series is midnight Pacific Time which translates to 8 in the morning in UTC-0. That's a 4 hour difference to what the API tells me.

Am i missing something here? Or did i just caught a bug?

Another example is "DC’s Legends of Tomorrow". In reality this airs at 9:00 PM EST. That translates to 2 (AM) in UTC-0. The API tells me it's "2022-02-03T01:00:00+00:00" which would be 1AM and is thus wrong. Or i perceive it as wrong ;)

I'm sure i can find more examples but these 2 should do to make my point. There's either a bug in this series too or a wrong understanding on my part for interpreting these stamps.

@markg85 wrote:
Another example is "DC’s Legends of Tomorrow". In reality this airs at 9:00 PM EST. 

I haven't checked whether that's correct, but that's not what we have: https://www.tvmaze.com/episodes/2248696/dcs-legends-of-tomorrow-7x10-the-fixed-point shows the episode airs at 8PM EST. Which correctly translates to T01:00:00+00:00 :)

@markg85 wrote:
Hi again,

Sorry for reviving this now 3 years old thread. I'm still using this api and still have troubles with this very specific part. 

Let's take "The Book of Boba Fett" as an example here. When i view it's information (this call) then i see that the episodes air at "2021-12-29T12:00:00+00:00". According to information provided in this very forum thread, i should be able to just interpret that timestamp to my local time. As the timestamp should be the actual airdate in UTC-0 according to earlier information.

As for Boba Fett (which airs on Disney+): for global web channels (that operate in more than one country) we don't support airtimes, because the exact premiere time usually varies per country. Instead, these are fixated on the arbitrary time of 12:00 afternoon GMT.

@david wrote:
I haven't checked whether that's correct, but that's not what we have: https://www.tvmaze.com/episodes/2248696/dcs-legends-of-tomorrow-7x10-the-fixed-point shows the episode airs at 8PM EST. Which correctly translates to T01:00:00+00:00 :)

Exactly the thing i pointed out. That 8PM is wrong. It airs at 9PM

So i suppose you just confirmed my finding.

@david wrote:
As for Boba Fett (which airs on Disney+): for global web channels (that operate in more than one country) we don't support airtimes, because the exact premiere time usually varies per country. Instead, these are fixated on the arbitrary time of 12:00 afternoon GMT.

 

That's weird. The series does not have a release date per country. It explicitly has a release date of being aired everywhere at the same time. So the for this episode should be midnight Pacific Time which in your logic translates to a time of 8 in the morning. See my post above where i explained this.

In other terms. When it's midnight Pacific Time, the episode gets released worldwide whatever time it is.

Legends airs at 8pm this season.