EarthTools

Webservices
jstott.me.uk > EarthTools > Webservices

Here's a collection of webservices for finding out geographical-related information. There are currently three services available for finding the time zone or local time, the sunrise and sunset times, and the elevation/height above sea level at a given latitude and longitude.

Note that due to abuse, the height webservice is currently disabled. At one point on August 1, someone was making 35 requests per second. The service will remain disabled until I can implement a system to guard against this.

Are you just looking for the sunrise or sunset time, time zone and local time or height/elevation for somewhere in the world?
The main EarthTools site uses a point-and-click map interface or the ability to search for a particular place from a database of nearly 7.5 million place names.

Updated 27th July 2008. Added a crossdomain.xml policy to allow cross-domain requests to be made on the web services from Flash applications.
Updated 18th February 2007. Important new usage restrictions .
Updated 6th May 2006. Added dst elements to the time zone XML response. Daylight saving time information is currently available for Western Europe.
Updated 29th December 2005. Added Height Above Sea Level webservice.
Updated 8 December 2005. Added version , isotime and utctime elements to the time zone XML response. Also made available time zone data covering the entire world.

Keep up to date by sending an e-mail to the author. I'm keen to know where the webservices are being used! I can also send you updates whenever changes are made to how to access services or the data that can be accessed. Ideas for improvement, notifications of significant error in the data or just general comments are also more than welcome.

Although these services are free, you are more than welcome to make a donation using PayPal to support the running costs of the site.

Disclaimer: The data obtained by using these webservices is provided "as is". I can not make any guarantees over its accuracy. Use of the data is entirely at your own risk.

Contact the author: If you have an comments or queries, feel free to contact me by e-mail: webservices@earthtools.org.

Usage Restrictions

Usage of these services is currently free of charge. However, there are two important rules to follow when using these webservices:

  1. You must not make more than one request per second to these webservices.
  2. You must cache results if you believe that you will need to make another identical request within any 24-hour period.
  3. You must delete any cached data when you no longer need it and in any case after 14 days. You should then make a new request for the data in line with the previous two rules. If you wish to keep access to data I am able to license the data for use in this way.

Usage is logged and anyone not complying with these rules may find their usage of the webservices restricted or removed without warning. Some people may want to make a one-off run of a batch of requests - if you wish to do this, contact me to find out when best to do this.

These restrictions were introduced on 18th February 2007 following a significant increase in the use of the webservices. At present, approximately one hundred million requests per week are being made. I want to continue providing these services for free, but the cost of providing them may become prohibitive in the future.

Contact me if you are concerned about your use of these webservices.

Time Zone and Local Time

This service responds with the time zone and local time at the given latitude and longitude. Daylight Saving Time is currently taken into account for Western Europe (areas covered by the UTC+0 and UTC+1 time zones). To access the service, use:

http://www.earthtools.org/timezone/<latitude>/<longitude>

where <latitude> and <longitude> should be replaced with the latitude and longitude of the place to query. Note that the query should be entered without the <s or >s (as shown in the example below).

Here's an example for New York: 

http://www.earthtools.org/timezone/40.71417/-74.00639

which returns the following XML:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<timezone xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.earthtools.org/timezone.xsd">
    <version>1.1</version>
    <location>
        <latitude>40.71417</latitude>
        <longitude>-74.00639</longitude>
    </location>
    <offset>-5</offset>
    <suffix>R</suffix>
    <localtime>4 Dec 2005 12:06:56</localtime>
    <isotime>2005-12-04 12:06:56 -0500</isotime>
    <utctime>2005-12-04 17:06:56</utctime>
    <dst>False</dst>
</timezone>

To request different versions of the service, append the service name part with the relevant version number. This guarantees that the response will always be in the expected format. If you don't specify the version number, the latest version of the service will respond. Here is an example of how to modify the above request to include the version number:

http://www.earthtools.org/timezone-1.1/40.71417/-74.00639

The latest version of this service is 1.1.

Here is a detailed description of each element in the response:

Data Coverage

Time zone data is available covering the entire world. Daylight saving time data is more limited but is gradually improving. Daylight saving time information is known about for those parts of Western Europe that are covered by the UTC+0 and UTC+1 time zones.

Resolution and Accuracy

Data is provided at a resolution of 2.5 arc minutes per data point. Accuracy is good but errors may be apparent close to the boundaries between time zones owing to the manner in which the data was sourced.

Sunrise and Sunset Times

This service responds with the sunrise, sunset and twilight times for the specified latitude and longitude and date. To access the service, use:

http://www.earthtools.org/sun/<latitude>/<longitude>/<day>/<month>/<timezone>/<dst>

where:
latitude - decimal latitude of the point to query (from -90 to 90).
longitude - decimal longitude of the point to query (from -180 to 180).
day - day to query (from 1 through 31).
month - month to query (from 1 through 12).
timezone - hours offset from UTC (from -12 to 14). Alternatively, use '99' as the timezone in order to automatically work out the timezone based on the given latitude/longitude.
dst - whether daylight saving time should be taken into account (either 0 for no or 1 for yes).
Note that the query should be entered without the <s or >s (as in the example below).

Here's an example for New York for the 4th December: 

http://www.earthtools.org/sun/40.71417/-74.00639/4/12/-5/0

which returns the following XML:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<sun xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.earthtools.org/sun.xsd">
    <version>1.0</version>
    <location>
        <latitude>40.71417</latitude>
        <longitude>-74.00639</longitude>
    </location>
    <date>
        <day>4</day>
        <month>12</month>
        <timezone>-5</timezone>
        <dst>0</dst>
    </date>
    <morning>
        <sunrise>07:05:34</sunrise>
        <twilight>
            <civil>06:34:51</civil>
            <nautical>06:00:36</nautical>
            <astronomical>05:27:25</astronomical>
        </twilight>
    </morning>
    <evening>
        <sunset>16:27:01</sunset>
        <twilight>
            <civil>16:57:44</civil>
            <nautical>17:31:59</nautical>
            <astronomical>18:05:10</astronomical>
        </twilight>
    </evening>
</sun>

To request different versions of the service, append the service name part with the relevant version number. This guarantees that the response will always be in the expected format. If you don't specify the version number, the latest version of the service will respond. Here is an example of how to modify the above request to include the version number:

http://www.earthtools.org/sun-1.0/40.71417/-74.00639/4/12/-5/0

The latest version of this service is 1.0.

version gives the version number of the request - this is currently always 1.0 but may change if modifications to the output are required.

About the Sunrise and Sunset Time Calculations

Sunrise and sunset times are calculated using a PHP script using formulae from www.srrb.noaa.gov. There might be errors when using latitudes which are close to the poles.

Elevation/Height Above Sea Level

This service responds with the height above sea level at the given latitude and longitude. To access the service, use:

http://www.earthtools.org/height/<latitude>/<longitude>

where <latitude> and <longitude> should be replaced with the latitude and longitude of the place to query. Note that the query should be entered without the <s or >s (as shown in the example below).

Here's an example for Birmingham, UK: 

http://www.earthtools.org/height/52.4822/-1.8946

which returns the following XML:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<height xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.earthtools.org/height.xsd">
    <version>1.0</version>
    <location>
        <latitude>52.4822</latitude>
        <longitude>-1.8946</longitude>
    </location>
    <meters>141</meters>
    <feet>462.6</feet>
</height>

To request different versions of the service, append the service name part with the relevant version number. This guarantees that the response will always be in the expected format. If you don't specify the version number, the latest version of the service will respond. Here is an example of how to modify the above request to include the version number:

http://www.earthtools.org/height-1.0/52.4822/-1.8946

The latest version of this service is 1.0.

The given latitude and longitude are repeated in the location element. The meters element gives the height above sea level in metres and the feet element gives the height above sea level in feet (rounded to one decimal place). If the requested point is outside the area of coverage, both the meters and feet elements will contain 'Unknown'. If the point is within the area of coverage but over sea, then the meters and feet elements may contain 'Unknown' or '-9999'. version gives the version number of the request - this is currently always 1.0 but may change if modifications to the output are required.

Data Coverage

Data is available covering all of mainland Europe and the United States of America. European coverage covers the area bounded by 35°N and 60°N and 15°W and 35°E. American coverage covers the area bounded by 20°N and 50°N and 65°W and 125°W. I intend to extend the coverage of that data to the rest of the world (as and when the space available for hosting increases to hold the data!).

Resolution and Accuracy

The terrain model used to find heights above sealevel is from the Shuttle Radar Topography Mission (SRTM) which was a joint project between the US National Geospatial-Intelligence Agency (NGA) and the National Aeronautics and Space Administration (NASA). Data was recorded for 11 days from the Space Shuttle Endevour from 11th February 2000. The data used here is at a resolution of 3 arc seconds (approximately 90m).

© 2005-11, Jonathan Stott.