Marine Institute ERDDAP Server Serving data from the Marine Institute (Ireland)

www.marine.ie

ERDDAP > convert > time

Convert a Numeric Time to/from a String Time

• UDUNITS-compatible Number - for example, 473472000 "seconds since 1970-01-01T00:00:00Z", or
• ISO 8601:2004 "extended" format String in the form YYYY-MM-DDThh:mm:ssZ - for example, 1985-01-02T00:00:00Z .

Reset the form to the default values.

Or, bypass this web page and do time conversions from within a computer program.

Notes about the Time Converter

• DISCLAIMER OF LIABILITY - No person or organization associated with this web site
  makes any warranty, express or implied, including warranties of merchantability
  and fitness for a particular purpose, or assumes any legal liability for the accuracy,
  completeness, or usefulness, of any information at this web site.
   
• UDUNITS Time Units - For example, "seconds since 1970-01-01T00:00:00Z".

  The first word can be (upper or lower case):
    ms, msec, msecs, millis, millisecond, milliseconds,
    s, sec, secs, second, seconds,
    m, min, mins, minute, minutes,
    h, hr, hrs, hour, hours,
    d, day, days,
    week, weeks,
    mon, mons, month, months,
    yr, yrs, year, or years.

  "since" is required.

  The time can be any time in the format YYYY-MM-DDThh:mm:ssZ .
  The T, hh, :mm, :ss, and Z parts are optional.

  So another example is "hours since 0001-01-01".

  Technically, ERDDAP does NOT follow the CF standard when converting "years since"
  and "months since" time values to "seconds since". The CF standard defines a
  year as a fixed, single value: 3.15569259747e7 seconds. And CF defines a month
  as year/12. Unfortunately, most/all datasets that we have seen that use
  "years since" or "months since" clearly intend the values to be calendar years
  or calendar months. For example, "3 months since 1970-01-01" is usually intended
  to mean 1970-04-01. So, ERDDAP interprets "years since" and "months since" as
  calendar years and months, and does not strictly follow the CF standard.

• Invalid Input - ERDDAP tries to deal with improperly formatted input.
  If the input can't be dealt with, ERDDAP will generate an error message.
   

How ERDDAP Deals with Time

• Time is a difficult, complex, messy issue.
   
• Goal - An underlying goal for ERDDAP's system for dealing with time is to have a single
  system that allows time data from any dataset to be compared directly to time data from
  any other dataset. Please keep that in mind when you read the other comments below.
   
• Time Points - ERDDAP only deals with time points (a combined date+time in the
  Zulu time zone, each an instant in time).
   
• Time Zones - ERDDAP always uses the Zulu (UTC, GMT) time zone and never uses
  daylight savings times. Time data from a source with time zone information (which
  may incorporate daylight savings time information) is converted to Zulu time.
  Time data from a source without time zone information is assumed to be already in
  Zulu time.
   
• Precision - ERDDAP deals with time internally as "seconds since 1970-00-00T00:00:00Z",
  ignoring leap seconds (see below), stored as double precision floating point numbers.
  Thus, most time data can be stored very precisely (roughly to the nearest microsecond,
  but progressively less precisely very far in the past or future).
   
• Consistent Units - Using the same units for time ("seconds since 1970-00-00T00:00:00Z")
  for all datasets allows times from different datasets to be compared easily.
  Seconds are the International System of Units (SI) base unit of time.
  1970-01-01T00:00:00Z is the start of the Unix epoch, which is widely used by computer
  operating systems. "seconds since 1970-00-00T00:00:00Z" are widely used and are
  often called Unix time or epoch seconds. The use of the units string
  "seconds since 1970-00-00T00:00:00Z" makes Unix time compatible with UDUNITS-2 and
  the Climate and Forecast Metadata Conventions (CF), which uses UDUNITS-2 for units
  definitions.
   
• Text Representation - By default, when formatting times as text, ERDDAP uses the
  ISO 8601:2004 "extended" format String, truncated to the second
  (e.g., 2011-04-26T14:07:12Z). (Related humor: http://xkcd.com/1179/)
  ERDDAP administrators can configure a given dataset to display the time data values
  truncated to 0.001 second, 0.01 second, 0.1 second, second, minute, hour, date, or month
  to indicate the precision of the time data values.

  When reading ISO 8601 times with decimal seconds, ERDDAP accepts a period separator
  (e.g., 2011-04-26T14:07:12.059Z) or a comma separator (e.g., 2011-04-26T14:07:12,059Z).
  Currently, when writing ISO 8601 times ERDDAP always uses a period separator.
   

• Gregorian Calendar - ERDDAP uses the Gregorian Calendar for times after the
  discontinuity in 1582 and the Julian calendar for times before the discontinuity.
  (The ISO 8601:2004 standard doesn't specify how to handle times before 1582.)
  See the Java GregorianCalendar class (which ERDDAP uses) for details.
  For example, 17611992 hours since 0001-01-01T00:00:00Z = 2010-03-01T00:00:00Z
  (see for yourself)
   
  Currently, ERDDAP does not support any other calendar (including the noleap, 365_day,
  360_day, and Julian calendars defined by the CF metadata conventions). However, you
  can store such data in ERDDAP by storing the numbers or Strings in a variable that is
  named something other than "time" and doesn't include "since" in the units metadata.
  Then, ERDDAP won't interpret the values as times and won't convert the data to
  "seconds since 1970-01-01T00:00:00Z". Users will be able to access the data in its
  original form.
   
• BC Years - As specified in the ISO 8601:2004 standard, ERDDAP just uses the AD
  (not the BC) era for year numbers. The normal Julian sequence of years near the
  era transition is 2 BC, 1 BC, 1 AD, 2 AD. Because oceanographers and climatologists
  often use year 0000 for climatologies, and because ISO 8601:2004 specifies this, the
  years near the era transition in ERDDAP are -0001, 0000, 0001, 0002, respectively.
  Thus, for BC years: ERDDAPYear = 1 - BCYear (see for yourself: test1, test2 and test3).
  With that in mind, ERDDAP should work for dates far in the past and future.
   
• UTC - As much as is practical, ERDDAP, like Unix time and UDUNITS-2, uses the
  Coordinated Universal Time (UTC) time system. UTC is the modern version of the GMT
  time system. UTC uses occasional leap seconds to stay close to the International Atomic
  Time (TAI). GPS devices use GPS time (which doesn't use leap seconds) internally,
  but display UTC time to users. (See http://tycho.usno.navy.mil/systime.html or other
  discussions of Systems of Time.) Strictly speaking, UTC can't be used in some
  situations for far future times (e.g., in models), since the occurrence of leap
  seconds can't be predicted.
   
• Leap Seconds - Like Unix time and UDUNITS-2, ERDDAP's
  "seconds since 1970-00-00T00:00:00Z" is a numeric encoding (which doesn't use leap
  seconds) of UTC time (which does use leap seconds). When converting string times
  to/from numeric times, ERDDAP, like Unix time and UDUNITS-2, ignores leap seconds.
  Yet, ERDDAP, Unix time, and UDUNITS-2 numeric times all say they use UTC.
  Here's why and how:
  Since computer clocks are not good time keepers, they drift from UTC time and have
  to be reset to UTC time occasionally. Unix time treats leap seconds as part of the time
  deviation caused by the clock's drift. This allows software to do time encoding and
  time calculations and ignore leap seconds. With ERDDAP, Unix time, and UDUNITS-2
  numeric time values, all minutes are treated as having 60 seconds, even though UTC
  minutes with leap seconds have 61 seconds. Note that database programs like Oracle,
  MySQL (and so probably MariaDB also), PostgreSQL, and languages like C# also
  basically try to ignore leap seconds.
  This won't cause problems when converting UTC String date+time+timeZone values into
  ERDDAP numeric values if the times are then reconverted back to date+time+Zulu
  Strings in a way that also ignores leap seconds. The two errors will cancel each
  other out. One unfortunate consequence is that ERDDAP, Unix time, and UDUNITS-2
  numeric times have no mechanism to encode actual leap seconds as numbers
  unambiguously. For example, both the leap second 2008-12-31T23:59:60Z and the
  next second 2009-01-01T00:00:00Z are encoded as
  1230768000 seconds since 1970-01-01T00:00:00Z. This is a flaw, but only affects
  actual leap seconds. Similarly, if you need to calculate the exact number of UTC
  seconds between two points in time, you can use ERDDAP to handle the time data,
  but subtracting one numeric time value from the other is just the first step in
  the calculation. You need manually adjust that value by consulting a
  table of leap seconds.
   
• Low Resolution Times and Time Spans (Time Ranges) - If time data was recorded to
  a lower resolution (e.g., a minute, hour, day, month, or year) or represents a time
  span (e.g., a specific hour, day, 7-day period, month, year), ERDDAP requires that
  a time point (we call it the "nominal time") be used to represent that time or time
  span. Using a nominal time allows time points, low resolution time points, and time
  spans to be interoperable. (Imagine visualizing different datasets in a program like
  Google Earth and using a time slider to control which subset of data is visible.)
  The most commonly selected time points for the nominal time are the start time and
  the centered time (less common, but has advantages for use with time sliders). We
  recommend that you use the long_name metadata to identify this (e.g., "Start Time" or
  "Centered Time"). For low resolution times, consider e.g., "Date", "Month", and "Year".
  And/or, put the details in the variable's "comment" metadata.
   
  Or, to more accurately represent time spans, you can set up a dataset to have both
  a beginTime and an endTime variable (and even a centeredTime, if you want
  to cover all possibilities).
   
• These are imperfect answers. The current setup deals reasonably well with most
  situations and matches most people's expectations about how time works (even if they
  haven't thought about it in detail), but not all. But that's the way ERDDAP works
  currently.
   

Want To Do Time Conversions from within a Computer Program?

• An example which converts a numeric time to a string time is
  http://erddap2.marine.ie/erddap/convert/time.txt?n=473472000&units=seconds%20since%201970-01-01T00:00:00Z
   
• An example which converts a string time to a numeric time is
  http://erddap2.marine.ie/erddap/convert/time.txt?isoTime=1985-01-02T00:00:00Z&units=seconds%20since%201970-01-01T00:00:00Z