IRIS Seismographs in Schools API Documentation

The IRIS Seismographs in Schools API is best described as a generic REST API. This API gives third parties the ability to write applications that access data from the IRIS SIS Website. You can read more about REST here. The easiest way to think of the API is a series of URLs that can be called and sometimes passed input parameters. These URLs then return XML that can be processed by other applications.

The XML outputted by the API can be read and interpreted by any programming language. At the bottom of this page a small sample application is provided in PHP.

Please do not deploy your finished application to query this API every time a page is viewed. A much better approach is to query the API daily (or more often if necessary) and store copies of these files on your local server. You can then process these local files when the data is needed. This will make your application faster and will place less of a burden on our servers.

The SIS API consists of 6 functions that can be called to return data from the SIS website. When visiting the URLs below in a browser, it helps if you view the source of the page which will format the XML properly and make it much easier to understand. Viewing the XML that these functions output in your browser will make them much easier to understand and write applications around.

Get All Stations

http://www.iris.edu/hq/ssn/api/get_all_stations
http://www.iris.edu/hq/ssn/api/get_all_stations/UK
http://www.iris.edu/hq/ssn/api/get_all_stations/UK/30
http://www.iris.edu/hq/ssn/api/get_all_stations/ALL/60

This function retrieves a list of information describing all stations currently registered with IRIS SIS.

There are two optional arguments as well. The first is the 2 or 3 digit regional network code. Passing this will only retrieve stations that belong to the associated regional network. The second is the number of days that a station must have uploaded data within. Calling /get_all_stations/UK/30 will only return stations belonging to the UK regional network that have uploaded data within the last 30 days. If you want a list of all stations regardless of network, but still want to specify this argument, you must use ALL for the network code such as /get_all_stations/ALL/30

Get Station Info

http://www.iris.edu/hq/ssn/api/get_station_info/LHST
http://www.iris.edu/hq/ssn/api/get_station_info/LHST/2008-12-30
http://www.iris.edu/hq/ssn/api/get_station_info/LHST/2008-12-30/2009-03-16

This function retrieves information about a single station and the data files uploaded by that station. The arguments for this function are explained below.

The Get Station Info function has one required argument and two optional arguments that are passed in the URL. The first argument is a valid 4 character station code. This must be a station that is registered with IRIS SIS. The second argument (optional) is a filter to only retrieve events uploaded by this station after a certain date. The third argument is a filter to only retrieve events uploaded before a certain date.

If neither a start or end date are specified, this function will default to displaying events uploaded by this station for the last 30 days.

The three URLs above represent 3 different function calls to Get Station Info with passing in different arguments. This first will retrieve all information about LHST and any event files that it has uploaded in the last 30 days. The second URL will do the same as the first URL, but it will return all events after December 30th, 2008. The third URL will do the same as the second URL, but will not return any events before March 16th, 2009.

The format for dates is YYYY-MM-DD. So a URL consists of:

http://www.iris.edu/hq/ssn/api/get_station_info/{4DIGITSTATIONCODE}/{10DIGITAFTERDATE}/{10DIGITBEFOREDATE}

Get Events

http://www.iris.edu/hq/ssn/api/get_events
http://www.iris.edu/hq/ssn/api/get_events/2008-12-30
http://www.iris.edu/hq/ssn/api/get_events/2008-12-30/2009-03-16

This function retrieves a list of events and also stations that have uploaded data for those events. An event must have at least one data file uploaded for it be returned.

This function takes two optional arguments for after and before. These work identically to the arguments described for Get Station Info. If these arguments are not specified, then only events for the last 30 days will be returned.

Get Event Info

http://www.iris.edu/hq/ssn/api/get_event_info/4926

This function returns information about an event and any data files that were uploaded for that event.

This function takes one required argument which is event id. This event id is internal to the IRIS SIS database and is not related to anything else. This id can be retrieved by calling Get Station Info or Get Events and looks like <event id="4926">

Get All Networks

http://www.iris.edu/hq/ssn/api/get_all_networks

This function returns a list of all regional networks that are affiliated with IRIS SIS.

Get Latest Sacfiles

http://www.iris.edu/hq/ssn/api/get_latest_sacfiles
http://www.iris.edu/hq/ssn/api/get_latest_sacfiles/100
http://www.iris.edu/hq/ssn/api/get_latest_sacfiles/ALL

This function returns info about the latest SAC files that have been uploaded. By default the last 30 uploaded files will be returned. There is one optional argument which can be passed to modify the number of SAC files returned. The URL first URL above for example would return the last 100 SAC files. You can also pass in the word ALL to return all SAC files that have ever been uploaded.

Example Application

Below is a sample application written PHP that uses the SIS API to display a table of recent events and list the stations that uploaded data for them.

View the source code for this application.

IDRegionDateStations
45595117km WNW of Hofn, Iceland2014-10-31 01:30:42DL02
45504128km NNE of Vik, Iceland2014-10-27 01:05:19DL02
45484109km WNW of Hofn, Iceland2014-10-26 05:54:48DL02
45455114km WNW of Hofn, Iceland2014-10-25 01:48:40DL02
4544023km E of Mawlaik, Burma2014-10-24 05:11:56CMTH
4543454km NW of Mawlaik, Burma2014-10-24 00:05:27CMTH
4537190km WNW of Hofn, Iceland2014-10-21 08:36:41DL02 WORDW
45341118km WNW of Hofn, Iceland2014-10-20 01:00:25DL02
45293111km WNW of Hofn, Iceland2014-10-18 09:40:13DL02 DIAS WORDW
45244109km WNW of Hofn, Iceland2014-10-16 03:14:59DL02
4522853km ESE of Dehloran, Iran2014-10-15 13:35:53CYPPA
45226124km NNE of Vik, Iceland2014-10-15 11:16:33DL02 DIAS WORDW
4518864km S of Intipuca, El Salvador2014-10-14 03:51:38MAOK MCMI CN01 DIAS WORDW DL02 KCMA CYPPA FWCT
45142117km S of Akureyri, Iceland2014-10-12 21:23:14DL02
45126122km WNW of Hofn, Iceland2014-10-12 08:43:44DL02 DIAS