Astronomy API: Tides Service

Get Tidal Predictions for a Specific Place and Time Interval.

Documentation

The Tides Service can be used to retrieve predicted tidal information over a given time interval for a specific place.

Request Endpoint

HTTP Endpoint: https://api.xmltime.com/tides

Request Parameters

Name	Description	Required
placeid	Specify the ID of the location you would like to retrieve information for. To retrieve the information for multiple places, the corresponding IDs can either be specified as a comma separated list, or by supplying the parameter multiple times (or any combination). Note: It is also possible to specify coordinates or IATA/ICAO codes for airports, see the documentation for the type Location Id for detailed information. Type: `String` / Location Id	Yes
startdt	Start of the requested time interval. Defaults to the current date if not specified. Type: `String` / ISO8601 Timestamp	No
enddt	End of the requested time interval. Defaults to the current date if not specified. Cannot be more than 14 days after the start date. Type: `String` / ISO8601 Timestamp	No
onlyhighlow	Whether to return every point per interval, or just the highest and lowest points. Type: `Boolean` Accepted values: `0` or `1` Default value: `1`	No
interval	Interval between each data point in minutes. Type: `Integer` Accepted values: `5`, `15`, `30`, or `60` Default value: `30`	No
subordinate	Whether to resolve subordinate stations, or just reference stations. Type: `Boolean` Accepted values: `0` or `1` Default value: `0`	No
radius	Search for tidal stations within a given radius from the requested place. Type: `Integer` Default value: `25`	No
localtime	Whether input and output timestamps should be resolved to local time. Timestamps are by default resolved to UTC. Type: `Boolean` Accepted values: `0` or `1` Default value: `0`	No
tz	Add time zone information under the `date` object. Type: `Boolean` Accepted values: `0` or `1` Default value: `1`	No
verbosetime	Adds verbose time specification to all ISO 8601 time stamps. Type: `Boolean` Accepted values: `0` or `1` Default value: `1`	No
template	Specify the name of a template if you want the result rendered in a specific format (e.g. CSV). Type: `String` Accepted values: `csv` or `xlsx` Default value: `None`	No

Response Elements:

Name	Description
station (XML), stations (JSON)	This element wraps the information for the locations in the request which sucessfully resolved to a tidal station. For the XML format, it will be repeated multiple times, while for JSON, it is modeled as an array of objects with the same content. Type: `Array` of StationType

Supported Templates:

csv

To use this template, specify this parameter combination: out=text&template=csv.

This template is used to retrieve the calendar events in CSV format. The result contains one line per tidal data point.

xlsx

To use this template, specify this parameter combination: out=blob&template=xlsx.

This template is used to retrieve a binary file of tidal data in an Excel/Office Open XML format.

The template returns a binary file with the MIME type set to application/vnd.openxmlformats-officedocument.spreadsheetml.sheet. Ideally, the contents of this binary file would be saved to disk, or served to a user, as an .xlsx file.

Example JSON Request:

https://api.xmltime.com/tides?placeid=norway/sola&startdt=2021-07-07T07:30:00&enddt=2021-07-07T23:59:59&version=3&out=json&prettyprint=1&accesskey={KEY}&expires={TIMESTAMP}&signature={SIGNATURE}

Example JSON response:


{
	"version": 3,
	"billing": {
		"credits": 1
	},
	"stations": [{
		"source": {
			"name": "Risavika",
			"latitude": 58.916668,
			"longitude": 5.583333,
			"type": "Subordinate Station",
			"distance": 5.167779
		},
		"matchparam": "norway/sola",
		"result": [{
			"time": {
				"iso": "2021-07-07T13:48:06",
				"datetime": {
					"year": 2021,
					"month": 7,
					"day": 7,
					"hour": 13,
					"minute": 48,
					"second": 6
				}
			},
			"amplitude": 0.394788,
			"phase": "low"
		},{
			"time": {
				"iso": "2021-07-07T19:54:02",
				"datetime": {
					"year": 2021,
					"month": 7,
					"day": 7,
					"hour": 19,
					"minute": 54,
					"second": 2
				}
			},
			"amplitude": 0.688057,
			"phase": "high"
		}]
	}]
}

Example XML Request:

https://api.xmltime.com/tides?placeid=norway/sola&startdt=2021-07-07T07:30:00&enddt=2021-07-07T23:59:59&version=3&out=xml&prettyprint=1&accesskey={KEY}&expires={TIMESTAMP}&signature={SIGNATURE}

Example XML response:


<?xml version="1.0" encoding="UTF-8"?>
<data version="3">
  <billing>
    <credits>1</credits>
  </billing>
  <station matchparam="norway/sola">
    <source>
      <name>Risavika</name>
      <latitude>58.916668</latitude>
      <longitude>5.583333</longitude>
      <type>Subordinate Station</type>
      <distance>5.167779</distance>
    </source>
    <result>
      <tide>
        <time iso="2021-07-07T13:48:06">
          <datetime>
            <year>2021</year>
            <month>7</month>
            <day>7</day>
            <hour>13</hour>
            <minute>48</minute>
            <second>06</second>
          </datetime>
        </time>
        <amplitude>0.394788</amplitude>
        <phase>low</phase>
      </tide>
      <tide>
        <time iso="2021-07-07T19:54:02">
          <datetime>
            <year>2021</year>
            <month>7</month>
            <day>7</day>
            <hour>19</hour>
            <minute>54</minute>
            <second>02</second>
          </datetime>
        </time>
        <amplitude>0.688057</amplitude>
        <phase>high</phase>
      </tide>
    </result>
  </station>
</data>

Example CSV Request:

https://api.xmltime.com/tides?placeid=norway/sola&startdt=2021-07-07T07:30:00&enddt=2021-07-10T23:59:59&version=3&out=json&prettyprint=1&accesskey={KEY}&expires={TIMESTAMP}&signature={SIGNATURE}

Example CSV response:


Station name,Latitude,Longitude,Station type,Time,Amplitude,Tidal phase
Risavika,58.916668,5.583333,Subordinate Station,2021-07-07T13:48:06,0.394788,low
Risavika,58.916668,5.583333,Subordinate Station,2021-07-07T19:54:02,0.688057,high
Risavika,58.916668,5.583333,Subordinate Station,2021-07-08T02:14:41,0.397042,low
Risavika,58.916668,5.583333,Subordinate Station,2021-07-08T08:15:30,0.699662,high
Risavika,58.916668,5.583333,Subordinate Station,2021-07-08T14:27:00,0.385857,low
Risavika,58.916668,5.583333,Subordinate Station,2021-07-08T20:35:38,0.720782,high
Risavika,58.916668,5.583333,Subordinate Station,2021-07-09T02:54:24,0.379847,low
Risavika,58.916668,5.583333,Subordinate Station,2021-07-09T08:57:08,0.720987,high
Risavika,58.916668,5.583333,Subordinate Station,2021-07-09T15:02:05,0.375605,low
Risavika,58.916668,5.583333,Subordinate Station,2021-07-09T21:14:13,0.747488,high
Risavika,58.916668,5.583333,Subordinate Station,2021-07-10T03:30:37,0.363650,low
Risavika,58.916668,5.583333,Subordinate Station,2021-07-10T09:36:32,0.736374,high
Risavika,58.916668,5.583333,Subordinate Station,2021-07-10T15:35:24,0.363378,low
Risavika,58.916668,5.583333,Subordinate Station,2021-07-10T21:51:55,0.765206,high