Timestamps - localTimestamp/issueTimestamp, conversion, and URL parameters

[jcconnell]

Issue

There may be in issue with how the timestamps are handled in this library. I have reached out to MSW for additional information. Some questions that should be answered:

• When querying the API, should the timestamps provided to the start and end URL parameters be in the user's local time or in UTC?
• localTimestamp is described in the docs as Unix timestamp adjusted to represent local time for this location. Should this be converted to a Python datetime object as datetime.fromtimestamp() or datetime.utcfromtimestamp().
• issueTimestamp is described as in the docs as GMT unix time for the start of this forecast. Although we call it the ‘issue’ time it’ll always actually become available after this time because we need to create or obtain the model data and prepare it for delivery. Is this referring to the time when the forecast was made?

Observations

• Example query with start and end parameters set to datetime.now().timestamp() (1533770006.53376) returned:

[
  {
    "timestamp": 1533772800,
    "localTimestamp": 1533751200,
    "issueTimestamp": 1533729600,
    "fadedRating": 0,
    "solidRating": 0,
    "swell": {
      "absMinBreakingHeight": 0.82,
      "absMaxBreakingHeight": 1.28,
      "probability": 75,
      "unit": "ft",
      "minBreakingHeight": 1,
      "maxBreakingHeight": 1,
      "components": {
        "combined": {
          "height": 1.8,
          "period": 7,
          "direction": 268.24,
          "compassDirection": "E"
        },
        "primary": {
          "height": 0.9,
          "period": 7,
          "direction": 253.39,
          "compassDirection": "ENE"
        },
        "secondary": {
          "height": 0.9,
          "period": 8,
          "direction": 285.52,
          "compassDirection": "ESE"
        },
        "tertiary": {
          "height": 1.1,
          "period": 3,
          "direction": 303.51,
          "compassDirection": "ESE"
        }
      }
    },
    "wind": {
      "speed": 5,
      "direction": 305,
      "compassDirection": "SE",
      "chill": 91,
      "gusts": 9,
      "unit": "mph"
    },
    "condition": {
      "pressure": 1018,
      "temperature": 86,
      "weather": "1",
      "unitPressure": "mb",
      "unit": "f"
    },
    "charts": {
      "swell": "https://hist-1.msw.ms/wave/750/21-1533772800-1.gif",
      "period": "https://hist-1.msw.ms/wave/750/21-1533772800-2.gif",
      "wind": "https://hist-1.msw.ms/gfs/750/21-1533772800-4.gif",
      "pressure": "https://hist-1.msw.ms/gfs/750/21-1533772800-3.gif",
      "sst": "https://hist-1.msw.ms/sst/750/21-1533772800-10.gif"
    }
  }
]

• Converting localTimestamp to a datetime object produced these results:

>>> datetime.utcfromtimestamp(1533751200).strftime("%a %-I %p")
'Wed 6 PM'
>>> datetime.fromtimestamp(1533751200).strftime("%a %-I %p")
'Wed 2 PM'

• Converting issueTimestamp to a datetime object produced these results:

>>> datetime.utcfromtimestamp(1533729600).strftime("%a %-I %p")
'Wed 12 PM'
>>> datetime.fromtimestamp(1533729600).strftime("%a %-I %p")
'Wed 8 AM'

Theory

• localTimestamp should use datetime.utcfromtimestamp()
• issueTimestamp should use datetime.fromTimestamp()
• These seem contradictory to the documentation's description.

[tokyotribe]

I came across the same issue with localTimestamp when working with the MSW api directly. In particular, when daylight savings is applicable, the timestamp intervals in localTimestamp (when converted using datetime.fromTimestamp()) returned 01:00, 04:00, 07:00, etc. instead of 00:00, 03:00, 06:00. When I use datetime.utcfromtimestamp() instead, the intervals return as expected i.e. 00:00, 03:00, 06:00, etc. Sounds like your theory is right. Thanks for the pointer!