ArcGIS JavaScript Hack: Fixing dates from ArcGIS Server

Surprised by dates

Trouble with dates

A couple years ago, our company had developed a JavaScript-based web application, and it was in the middle of user acceptance testing when the client noticed something strange in the search results. When the client searched for her own property, she noticed that the date of sale showed March 17th, the day before she closed on her home (March 18th). Testing a few more places revealed that all sale dates displayed a date that was off by one in the search results.

What do we do when our data doesn’t look right? Well, we check the source, and that’s where things got weirder. When viewing the sale dates in ArcMap, the data showed the correct date. Her parcel record showed a sale date of March 18th. Republishing the data repeated the same scenario. How could the same data show one date in one technology, and another date in another format?

Time Zone Issues

The answer lies in time zones, and how both ArcGIS Server and your browser treat dates and times. If you store your data in an ArcGIS Server geodatabase, attributes with date formats are stored down to the millisecond. However, you can specify in your maps and data whether you’re interested in dates, times, or dates and times. If you’re only interested in dates, the times default to midnight UTC (Universal Time, formerly Greenwich Mean Time). In fact, until ArcGIS Server 10.4, you couldn’t specify any other time zone.

Okay, so dates were stored with a time of midnight UTC on the client’s server. ArcMap knew that, and treated the dates the same way. That’s how the sale date showed correctly on the client’s map for the service. When the map service was republished, and the data was queried through the REST service, the dates returned really big numbers, which represent the number of milliseconds between that date, and January 1, 1970 at midnight UTC.

Why, then, were the results showing different dates as if they were the day before on the website? When the browser works with dates, it knows something that ArcMap doesn’t account for… your time zone. Based on your browser’s location in the world, it can tell what time zone you’re in, and whether it honors daylight savings time.

When your browser uses JavaScript to create a date from the date attributes stored in a feature, it shows the date in your current time zone by default. Our client lives in the US in the Eastern time zone, which was five hours behind UTC. So, her date data, which was stored as midnight UTC, was appearing locally as 7:00pm the day before. And since we were ignoring the time, her results looked like they were showing the day before.

Mystery solved!

Resetting your dates

So, how do we deal with these dates that may not match your current time zone? The answer lies in JavaScript Date objects. For every function to get the year, month, day, and hour, there is a corresponding function to get it in UTC. So, if you construct your date using the feature data attribute, you can use these UTC functions to print out the corresponding date as if it was your time. Here’s an example below.

Sometimes, however, you don’t get access to what the ArcGIS JavaScript API is doing to your data before it displays it. For that, I’ll give you a more generic function for changing the data. It’s based on the assumption that you want to change any date-data where the time is midnight UTC (down to the millisecond). If you have other fields where the time is important, such as Last update or reporting date/time, the data would mostly be unaffected (provided it wasn’t updated/reported at midnight UTC).

Dates in ArcGIS Online Popups

If you’ve worked with the ArcGIS JavaScript API enough, you know that it handles a lot of UI and data manipulation for you. That’s great if it does what you want it to. But what if you want to show a date property in a popup created through an ArcGIS Online webmap, and it’s showing the wrong date (as in the case above)?

If you’re using the default Popup widget in the ArcGIS Online webmap, the trick is to access the data during the popup’s “set-features” event.  Here, you can loop through the selected features, access their graphics or feature layer (if available through a private _graphicsLayer property), and if there is field data on that layer, you can check those for date fields, and modify the date fields with the timeFix() method. It’s kinda experimental and subject to change as the JavaScript API changes. Also, this will only work on Your Application. It does not apply when looking at a web map in ArcGIS Online.

Why doesn’t ArcGIS Online do something like this?

The short response: How do you really know WHEN to apply this date formatting?

The longer response:

The truth is, it’s really hard to know when to apply this date/time fix. ArcMap is a desktop application that can keep track of a number of file-specific configurations, like removing time from dates, or showing numbers as currency. However, the ArcGIS REST API does not expose those custom formats. Numbers are numbers, whether they should be currency, area, or years. Date stamps are date stamps, whether the time is necessary or not. It’s up to the application consuming the map service data to display fields in the correct format.

We made a number of assumptions with the date hacks we added (each date at midnight UTC should be fixed, for one). Not everybody would like their data tweaked like that. You can’t please all the people all the time. That’s why I don’t mind patching it in as a hack on some of my applications.