Timezone Handling

RETS servers often support and deliver fields that contain DateTime fields. How these are expected to work and be used in regards to timezones changes based on a number of conditions.

RETS 1.5

When searching a DateTime field, the server expects that the timestamp you've provided represents the desired time in GMT/UTC.

When getting a DateTime field value back, the client should assume that the value given represents server local time.

Since RETS 1.5 doesn't support metadata which tells you the server's local timezone, the following rough process can be used to determine the server's timezone:

1. Pull and locate 1 record from the RETS server to use as a reference.
2. Within the reference listing, find 1) the timestamp field you're interested in searching, and 2) the value which represents the unique identifier for the listing (MLS#/ListingID) for example. For this example, we'll assume the timestamp (field: ModificationTimestamp) is 2012-12-22T10:30:40 and the MLS# (field: ListingID) is 352918
3. Issue a basic search for just that listing. For example: (ListingID=352918)
4. Modify your query to include the condition for the timestamp field. For example: (ListingID=352918),(ModificationTimestamp=2012-12-22T10:30:40) which likely won't return a result. If it does, the server is providing timestamps in GMT.
5. Proceed by adding 8 hours to the timestamp and re-search. If the listing is returned, the server is GMT-08:00 so you know that any timestamp you're given will need 8 hours added to it if you plan to search by it consistently.
6. Keep subtracting 1 hour and retry the request until the listing is returned. Once the listing is found, compare the timestamps to find the offset.

RETS 1.7.2

1.7.2 added a metadata entry that allows a server to advertise what timezone it's in. In addition, 1.7.2 added the ability for a RETS client to include timezone details directly in the query, placing responsibility for timezone conversion on the server.

A number of scenarios exist depending on different conditions. TimeZoneOffset below refers to the new attribute available through METADATA-SYSTEM (also shown at the top of retsmd.com).

1. When you search (ModificationTimestamp=2009-05-17T18:21:53+) and the TimeZoneOffset is set to -05:00, the server will assume the timestamp in your query is in -05:00. Note: this is a different default behavior when compared to RETS 1.5.
2. When you search (ModificationTimestamp=2009-05-17T18:21:53+) and the TimeZoneOffset is NOT set (or no value is given), the server will assume the timestamp in your query is GMT. This is more consistent with RETS 1.5 behavior.
3. When you search (ModificationTimestamp=2009-05-17T18:21:53-05:00+), the server will handle your timestamp as -05:00 (regardless of TimeZoneOffset)
4. When you search (ModificationTimestamp=2009-05-17T18:21:53Z+), the server will handle your timestamp as GMT (regardless of TimeZoneOffset) because the "Z" identifies GMT.
5. When you search (ModificationTimestamp=2009-05-17T18:21:53+00:00+), the server will handle your timestamp as GMT (regardless of TimeZoneOffset) because the "+00:00" also identifies GMT.

Here's the exact, relevant text from the RETS 1.7.2 specification:

Dates and times submitted in a query MAY utilize time offsets relative to UTC using the dmqldatetime If a dmqldatetime is submitted with time offset information, the server system MUST interpret the request using the time offset information. If the time offset is not declared in the query, the server system MUST interpret the request using the default System time zone offset. This default must match the advertised time zone offset of the SYSTEM-METADATA. If no time zone offset is advertised for the server system system, the default time zone offset MUST be UTC. The server system MUST interpret the TODAY token as the current date and time of the server system. For backward compatibility, the server system MUST treat clients with version less than 1.7.2 as submitting dates and times using a time zone offset of UTC/GMT. In this case, the advertised time zone offset is ignored since the client is not expected to be aware of the time zone offset. The server system MUST interpret the token NOW as the current date and time of the server system.