Date time format

The date and time appears frequently throughout the API. Understanding the format of the returned datetime object and how to utilize it is vital to getting the most out of the API. This page will provide a basic overview.

The Returned DateTime Object

The API returns the date as a UNIX timestamp in milliseconds:

/Date(1284497520000-0700)/

The three extra digits (in this case, zeros) found at the end of the timestamp are due to the object being returned in milliseconds. Remember, there are 1000 milliseconds in one second. The "0700" represents the timezone, in this example the U.S. Pacific (GMT-7) timezone.

There are two ways to account for the three extra digits. One is to divide the UNIX timestamp by 1000 prior to converting it. The second is to concatenate (remove) the last three digits.

DateTime Object with WCF Based Services

The WCF based services will provide a DateTime object from the .NET Framework. This means that there is no requirement to parse this timestamp if you are using WCF as the BCL will have already parsed the timestamp for the developer (regardless of the endpoint used).

Should the developer not use WCF to access the endpoints while building upon the .NET Framework, then they will be responsible for parsing the string to create a DateTime object.

Examples

Below are a few examples of different ways to convert the returned datetime object into a human-readable form.

Javascript

Example 1

The follow script converts the timestamp as returned by JSON into a javascript Date object for further manipulation.

function convertDate(timestamp)
{
    return new Date(parseInt(timestamp.substring(6,19)));
}
write convertDate(1234567890000).toLocaleString();
// Output:  Fri Feb 13 2009 23:30:30 GMT-0500 (Eastern Standard Time)
var dt = convertDate(1234567890000);
write dt.getHours() + ":" + dt.getMinutes();
// Output:  23:30

This code was written by TickleMeOzmo.

PHP

Example 1

function getTime($time){
$remove = array("/", "Date", "(", ")");
$time = str_replace($remove, "", $time);
$time = explode("-", $time);
$time[0] = $time[0] / 1000;
$time[0] = date('M-d-Y g:i a T', $time[0]);
return $time[0];
}

This code was written by Sunburned Goose

Fix applied by Barry Carlyon

Example 2

// To get a date
function parse_timestamp($timestamp) {
return date('M-d-Y g:i a T', substr($timestamp, 6, 10));
}
 
// To get a DateTime object
function parse_timestamp($timestamp) {
return new DateTime('@' . substr($timestamp, 6, 10));
}

This code was written by Ashfire908

Example 3

function getDate($timestamp)
{
    /* Time to mess with this weird looking string */
    if (preg_match('%/Date.(?P<date>[0-9]*)-%s', $timestamp, $regs)) {
 
        /* Get it in clean version, and delete the trailing zeros. */
        return date("F j, Y, g:i a", substr($regs['date'], 0, -3));
    }
}
/*
 * input:  /Date(1284497520000-0700)/
 * output: September 14, 2010, 8:52 pm
 */

This code was written by iBotPeaches

Example 4

This function converts the time into a different timezone so you can get times relative to you. You should only pick one of the two methods shown and comment out (or remove) the other. The date_create_from_format function is faster than the date_create. I left the return as a DateTime object so you can format how you want outside the function since you may not want to show it the exact same way on each page.

function parseJSONDate($theDate)
{
        $theDate = str_replace(array('/Date(', ')/'), '', $theDate);    // Remove the clutter
        $time[0] = substr($theDate, 0, 10);    // First 10 characters is UNIXTIME
        $time[1] = substr($theDate, -5);     // Last 5 characters is the TIMEZONE
 
        /* PHP 5.3.0 or greater */
        $theDate = date_create_from_format('U O', ($time[0] . ' ' . $time[1]));
        date_default_timezone_set("America/New_York");    // Change to your timezone.
 
        /* PHP 5.2.x */
        $theDate = date_create('@' . $theDate[0][0]);
        $theDate->setTimezone(new DateTimeZone("America/New_York"));    // Change to your timezone.
 
        return $theDate;
}
echo date_format(parseJSONDate("/Date(1234567890000-0700)/"), 'Y-m-d h:ia');
// Output:  2009-02-13 11:31pm
echo date_format(parseJSONDate("/Date(1234567890000-0700)/"), 'r');
// Output:  Fri, 13 Feb 2009 23:31:30 -0500

This code was written by dazarobbo and TickleMeOzmo.

Coldfusion

Example 1

Here is an example of a Coldfusion function which takes the CreateDate or ModifiedDate data from the API and returns a date/time object.

<cffunction access="public" name="parseReachTS">
  <cfargument name="reachTS" required="yes">
  <cfset parsedTS = DateAdd("s", Left(RemoveChars(reachTS,1,6),10), "01/01/1970")>
  <cfreturn parsedTS>
</cffunction>
<!---
    input:  /Date(1284497520000-0700)/
    output: {ts '2010-09-14 20:52:00'}
--->

This code was written by Shacky Meatwad

Ruby

Example 1

The following method takes the timestamp string as returned by JSON and returns a ruby Time object in UTC and a timezone string

def parse_timestamp(timestamp = nil)
  if timestamp && (timestamp =~ /^\/Date\((\d+)-(\d+)\)\/$/)
    return [Time.at($1.to_i / 1000).utc, $2]
  else
    raise ArgumentError.new('Invalid timestamp') 
  end
end
# input:  /Date(1284497520000-0700)/
# output: [Tue Sep 14 20:52:00 UTC 2010, "0700"]

This code was written by tquackenbush as part of [agoragames/halo-reach-api]