SuperDARN Mirror Catalogue API ============================== The |api_formal_title| provides access to data about the files and radars that make up the SuperDARN dataset. General ------- Content-Types ^^^^^^^^^^^^^ The API provides different content types which can be used to retrieve different types of representation of a requested resource. These content types are detailed in the following table. ================ ============================================================== Content-Type Description ================ ============================================================== application/json This returns the data encoded as JSON. This is the default. text/plain This returns the data encoded suitably for input to ``sha1sum`` (checksumReport). text/csv This returns the data encoded as comma separated variables (CSV). text/html This returns the documentation encoded as HTML. ================ ============================================================== Common Query Parameters ^^^^^^^^^^^^^^^^^^^^^^^ Each parameter is optional. These parameters may be used to control/filter output. ============== ================================================================ Parameter Description ============== ================================================================ contentType Can be used to return a particular content type, without having to set the Content-Type HTTP header (see `Content-Types`_). Example: ``contentType=checksumReport`` expanded Show the full data record for the requested resource. Boolean (true|false), default is false. Example: ``expanded=true`` timespan Filter the returned resources by a datetime range. Two ISO 8601 datetimes, separated by a forward slash. The datetimes can be partially specified, so for instance if a date only is specified, then the time will default to midnight. Example: ``timespan=2016-01-01T00:00:00/2016-01-01T23:59:59`` bbox Filter the returned resources by geographic bounding box. Two ordered pairs of coordinates, specifying the lower left and upper right extents of the bounding box, separated by commas. That is: minX,minY,maxX,maxY. The default spatial reference system is EPSG:4326, hence these are lon/lat. Example: ``bbox=-180,-90,180,0`` radar_code Filter the returned resources by three-letter radar code. Example: ``radar_code=hal`` distinct Specify whether to only show unique instances of transferred files. A file may be transferred on multiple occasions, but setting this to true will only show a single instance. Boolean (true|false), default is false. Example: ``distinct=true`` delimiter Specify an alternative delimiter for CSV encoded data. Default is ','. Example: ``delimiter=|`` includeHeaders Specify whether to include column headers for CSV encoded data. Boolean (true|false), default is true. Example: ``includeHeaders=false`` ============== ================================================================ Common Status Codes ------------------- The following HTTP status codes can be returned by the API. ==== ========================================================================== Code When ==== ========================================================================== 200 Status OK. All went fine. 400 Status Bad Request. The request data cannot be read. 404 Status Not Found. The resource is not available. 500 Status Internal Server Error. Please contact the webadmin. ==== ========================================================================== Resource Collections -------------------- A resource collection is a set of related data that are exposed via an API endpoint. For instance, all blacklisted files, or all small transferred files. URLs ^^^^ API calls are triggered by using the following URLs. .. csv-table:: :header: "Method", "Path", "Description" :widths: 6, 40, 50 GET, /superdarn/mirror/v3/, "Lists all resource collections." This call lists all API endpoints that return resource collections. Examples ^^^^^^^^ List All Resource Collections +++++++++++++++++++++++++++++ Request:: GET /superdarn/mirror/v3/ HTTP/1.1 Host: api.bas.ac.uk:80 Accept: application/json Response:: HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { "api_routes": [ { "method": "GET", "path": "/" }, { "method": "GET", "path": "/superdarn/mirror/v3/files/blacklisted" }, { "method": "GET", "path": "/superdarn/mirror/v3/files/blacklisted/:id" }, ... { "method": "GET", "path": "/superdarn/mirror/v3/" } ] } Files ----- These are the data files (``.dat``, ``.rawacf`` etc.) that make up the SuperDARN dataset. URLs ^^^^ API calls are triggered by using the following URLs. .. csv-table:: :header: "Method", "Path", "Description" :widths: 6, 40, 50 GET, /superdarn/mirror/v3/files, "Lists all files." GET, /superdarn/mirror/v3/files/:id, "Lists the file with id ``id``." By default, these calls will return a simple view which consists of the record's id, the filename and its checksum. Use the ``expanded`` query parameter to see the full record for a file. Note that with file queries, it is important to include query filter parameters to limit the API response that is returned. In particular, use of the ``timespan`` parameter is crucial to avoid returning an unwieldy response. Examples ^^^^^^^^ List All SAS Files for Given Timespan +++++++++++++++++++++++++++++++++++++ Request:: GET /superdarn/mirror/v3/files?timespan=2016-01-01/2016-01-01T23:59:59&radar_code=sas HTTP/1.1 Host: api.bas.ac.uk:80 Accept: application/json Response:: HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 [ { "id": 2, "filename": "20160101.0000.03.sas.rawacf.bz2", "checksum": "69d3ea9342a962e9d8e883563311ae4c4c27e6b1" }, { "id": 38, "filename": "20160101.0201.47.sas.rawacf.bz2", "checksum": "d9b0fe213cee5d0d3be592b636ed070289f810df" }, ... { "id": 236, "filename": "20160101.2201.47.sas.rawacf.bz2", "checksum": "4324cc51a2fe24bbe77584511143124fcd508b5b" } ] List File for Given Id ++++++++++++++++++++++ Request:: GET /superdarn/mirror/v3/files/2 HTTP/1.1 Host: api.bas.ac.uk:80 Accept: application/json Response:: HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { "id": 2, "filename": "20160101.0000.03.sas.rawacf.bz2", "checksum": "69d3ea9342a962e9d8e883563311ae4c4c27e6b1" } List Expanded View of File for Given Id +++++++++++++++++++++++++++++++++++++++ Request:: GET /superdarn/mirror/v3/files/2?expanded=true HTTP/1.1 Host: api.bas.ac.uk:80 Accept: application/json Response:: HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { "id": 2, "file_path": "/sddata/raw/2016/01/20160101.0000.03.sas.rawacf.bz2", "file_start_datetime": "2016-01-01T00:00:03.000Z", "file_end_datetime": "2016-01-01T02:00:00.000Z", "data_start_datetime": null, "data_end_datetime": null, "last_mod": "2016-01-02T20:05:21.000Z", "file_size": "52559583", "status_flag": 0, "checksum": "69d3ea9342a962e9d8e883563311ae4c4c27e6b1", "include_in_file_coverage": true, "include_in_data_coverage": true, "last_updated": "2016-07-20T12:08:27.000Z", "radar_code": "sas", "radar_short_code": "t", "radar_name": "Saskatoon", "file_type": "RAWACF" } Files with Alarm Conditions --------------------------- These are the data files that have been flagged with an alarm condition (non-zero status flag). For instance, those files that are blacklisted. URLs ^^^^ API calls are triggered by using the following URLs. .. csv-table:: :header: "Method", "Path", "Description" :widths: 6, 40, 50 GET, /superdarn/mirror/v3/files/blacklisted, "Lists all blacklisted files." GET, /superdarn/mirror/v3/files/blacklisted/:id, "Lists the blacklisted file with id ``id``." Examples ^^^^^^^^ List All Blacklisted Files ++++++++++++++++++++++++++ Request:: GET /superdarn/mirror/v3/files/blacklisted HTTP/1.1 Host: api.bas.ac.uk:80 Accept: application/json Response:: HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 [ { "id": 827868, "filename": "20110718.2221.47.kod.rawacf.bz2", "checksum": "7d98618998527aa28b343c67f589d7b14e8e266b" }, { "id": 827870, "filename": "20110718.2231.12.kod.rawacf.bz2", "checksum": "8bfb74ed4e651e7e549995e34e3a8cad8ed11fbc" }, ... { "id": 1777169, "filename": "20161018.2201.15.lyr.rawacf.bz2", "checksum": "b0279f6f6fc161ad36d7091ec63c6de1dd1eb529" } ] List All Blacklisted Files as Checksum Report +++++++++++++++++++++++++++++++++++++++++++++ Request:: GET /superdarn/mirror/v3/files/blacklisted?contentType=checksumReport HTTP/1.1 Host: api.bas.ac.uk:80 Accept: text/plain Response:: HTTP/1.1 200 OK Content-Type: text/plain; charset=utf-8 7d98618998527aa28b343c67f589d7b14e8e266b 20110718.2221.47.kod.rawacf.bz2 8bfb74ed4e651e7e549995e34e3a8cad8ed11fbc 20110718.2231.12.kod.rawacf.bz2 ... b0279f6f6fc161ad36d7091ec63c6de1dd1eb529 20161018.2201.15.lyr.rawacf.bz2 List All LYR Blacklisted Files for Given Timespan as Checksum Report ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Request:: GET /superdarn/mirror/v3/files/blacklisted?contentType=checksumReport\ ×pan=2016-10-01T00:00:00/2016-10-31T23:59:59&radar_code=lyr HTTP/1.1 Host: api.bas.ac.uk:80 Accept: text/plain Response:: HTTP/1.1 200 OK Content-Type: text/plain; charset=utf-8 cb51aae34f6040d6166185b2e2d65e962cab7e69 20161001.0001.00.lyr.rawacf.bz2 c120dff788cb6c50e158d845a4d56d49cf4cca14 20161001.0201.15.lyr.rawacf.bz2 ... b0279f6f6fc161ad36d7091ec63c6de1dd1eb529 20161018.2201.15.lyr.rawacf.bz2 Transferred Files ----------------- These are recorded instances of a given file being transferred (via ``rsync``, ``sftp`` etc.) from a PI institute, or another SuperDARN Mirror node. URLs ^^^^ API calls are triggered by using the following URLs. .. csv-table:: :header: "Method", "Path", "Description" :widths: 6, 40, 50 GET, /superdarn/mirror/v3/transferred/files, "Lists all transferred files, irrespective of whether an alarm condition occurred or not." GET, /superdarn/mirror/v3/transferred/files/:id, "Lists the transferred file with id ``id``." GET, /superdarn/mirror/v3/transferred/files/ok, "Lists all transferred files that transferred without an alarm condition occurring." GET, /superdarn/mirror/v3/transferred/files/ok/:id, "Lists the ok transferred file with id ``id``." By default, these calls will return a simple view which consists of the record's id, the filename and its checksum. Use the ``expanded`` query parameter to see the full record for a transferred file. Note that with transferred file queries, it is important to include query filter parameters to limit the API response that is returned. In particular, use of the ``timespan`` parameter is crucial to avoid returning an unwieldy response. List Expanded View of All Transferred Files for Given Timespan ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Request:: GET /superdarn/mirror/v3/transferred/files?expanded=true\ ×pan=2016-01-01T00:00:00/2016-01-01T23:59:59 HTTP/1.1 Host: api.bas.ac.uk:80 Accept: application/json Response:: HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 [ { "id": 1, "file_path": "/sddata/raw/2016/01/20160101.0000.03.pgr.rawacf.bz2", "file_start_datetime": "2016-01-01T00:00:03.000Z", "file_end_datetime": "2016-01-01T02:00:00.000Z", "data_start_datetime": null, "data_end_datetime": null, "last_mod": "2016-01-18T21:33:25.000Z", "file_size": "55835710", "status_flag": 0, "checksum": "f2f801bea1a9c7eb6b3daacadae63d92edbbc0fb", "include_in_file_coverage": true, "include_in_data_coverage": true, "last_updated": "2016-07-20T12:08:27.000Z", "radar_code": "pgr", "radar_short_code": "b", "radar_name": "Prince George", "file_type": "RAWACF", "transferred_file_status": null, "transfer_start_datetime": "2016-01-20T08:40:48.000Z", "transfer_end_datetime": "2016-01-20T09:25:20.000Z" }, ... { "id": 11, "file_path": "/sddata/raw/2016/01/20160101.0001.00.ker.rawacf.bz2", "file_start_datetime": "2016-01-01T00:01:00.000Z", "file_end_datetime": "2016-01-01T02:00:00.000Z", "data_start_datetime": null, "data_end_datetime": null, "last_mod": "2015-12-31T21:00:00.000Z", "file_size": "20448653", "status_flag": 0, "checksum": "f0556869d1bdb1891ceba7af6f205062b6c019e2", "include_in_file_coverage": true, "include_in_data_coverage": true, "last_updated": "2016-07-20T12:08:27.000Z", "radar_code": "ker", "radar_short_code": "p", "radar_name": "Kerguelen", "file_type": "RAWACF", "transferred_file_status": "old", "transfer_start_datetime": "2016-06-01T07:30:01.000Z", "transfer_end_datetime": "2016-06-01T09:50:32.000Z" }, ... ] Transferred Files with Alarm Conditions --------------------------------------- These are transferred files that have been flagged with an alarm condition (non-null transferred file status). For instance, those files that are too small. URLs ^^^^ API calls are triggered by using the following URLs. .. csv-table:: :header: "Method", "Path", "Description" :widths: 6, 40, 50 GET, /superdarn/mirror/v3/transferred/files/blacklisted, "Lists all files transferred that matched an entry in the blacklisted files list." GET, /superdarn/mirror/v3/transferred/files/blacklisted/:id, "Lists the blacklisted transferred file with id ``id``." GET, /superdarn/mirror/v3/transferred/files/old, "Lists all files transferred that were older than the two-month threshold." GET, /superdarn/mirror/v3/transferred/files/old/:id, "Lists the old transferred file with id ``id``." GET, /superdarn/mirror/v3/transferred/files/small, "Lists all files transferred that failed the too-small test (< 55 bytes)." GET, /superdarn/mirror/v3/transferred/files/small/:id, "Lists the small transferred file with id ``id``." GET, /superdarn/mirror/v3/transferred/files/compression/failure, "Lists all files transferred that failed the ``bzip2`` integrity check." GET, /superdarn/mirror/v3/transferred/files/compression/failure/:id, "Lists the compression failure transferred file with id ``id``." GET, /superdarn/mirror/v3/transferred/files/compression/exception, "Lists all files transferred that caused an unexpected ``bzip2`` exception." GET, /superdarn/mirror/v3/transferred/files/compression/exception/:id, "Lists the compression exception transferred file with id ``id``." GET, /superdarn/mirror/v3/transferred/files/notregular, "Lists all files transferred that failed the regular file test (``test -f``)." GET, /superdarn/mirror/v3/transferred/files/notregular/:id, "Lists the notregular transferred file with id ``id``." GET, /superdarn/mirror/v3/transferred/files/nomatch, "Lists all files transferred whose hash did not match that of a previous copy." GET, /superdarn/mirror/v3/transferred/files/nomatch/:id, "Lists the nomatch transferred file with id ``id``." GET, /superdarn/mirror/v3/transferred/files/alarm, "Lists all files transferred that had any alarm condition occur." GET, /superdarn/mirror/v3/transferred/files/alarm/:id, "Lists the alarmed transferred file with id ``id``." Examples ^^^^^^^^ List All Old Transferred Files ++++++++++++++++++++++++++++++ Request:: GET /superdarn/mirror/v3/transferred/files/old HTTP/1.1 Host: api.bas.ac.uk:80 Accept: application/json Response:: HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 [ { "id": 250349, "filename": "20140314.0201.00.sto.rawacf.bz2", "checksum": "c8a0ac0220b0bd68a3e77d0cca346cfc3fd1fad1" }, { "id": 348886, "filename": "20141210.0001.00.ker.rawacf.bz2", "checksum": "140cd12e2b644ee2997a265162e666c7e3a4d822" }, ... { "id": 1743340, "filename": "20160729.0800.11.ker.rawacf.bz2", "checksum": "cda9284eba0796336a72b45c41ce159f952e275b" } ] List Distinct Old Transferred Files as Checksum Report ++++++++++++++++++++++++++++++++++++++++++++++++++++++ Request:: GET /superdarn/mirror/v3/transferred/files/old?contentType=checksumReport\ &distinct=true HTTP/1.1 Host: api.bas.ac.uk:80 Accept: text/plain Response:: HTTP/1.1 200 OK Content-Type: text/plain; charset=utf-8 c8a0ac0220b0bd68a3e77d0cca346cfc3fd1fad1 20140314.0201.00.sto.rawacf.bz2 140cd12e2b644ee2997a265162e666c7e3a4d822 20141210.0001.00.ker.rawacf.bz2 ... cda9284eba0796336a72b45c41ce159f952e275b 20160729.0800.11.ker.rawacf.bz2 List Distinct KER Old Transferred Files for Given Timespan as Checksum Report +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Request:: GET /superdarn/mirror/v3/transferred/files/old?contentType=checksumReport&distinct=true\ &radar_code=ker×pan=2016-03-01T00:00:00/2016-03-31T23:59:59 HTTP/1.1 Host: api.bas.ac.uk:80 Accept: text/plain Response:: HTTP/1.1 200 OK Content-Type: text/plain; charset=utf-8 8e3859475b990726906d1d0e2ae38cd1d8b4d41f 20160301.0001.00.ker.rawacf.bz2 6c381e072efc3dc12fa2f749f5c1044e7b3cdf53 20160301.0201.00.ker.rawacf.bz2 ... 5044b6e746eb95c5ba5da80bc04fa7050bbbcb91 20160331.2201.00.ker.rawacf.bz2 List All Instances of Small Transferred File with Given File Id +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Request:: GET /superdarn/mirror/v3/transferred/files/small/1771737 HTTP/1.1 Host: api.bas.ac.uk:80 Accept: application/json Response:: HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 [ { "id": 1771737, "filename": "20160928.0602.00.bpk.rawacf.bz2", "checksum": null }, { "id": 1771737, "filename": "20160928.0602.00.bpk.rawacf.bz2", "checksum": null }, { "id": 1771737, "filename": "20160928.0602.00.bpk.rawacf.bz2", "checksum": null }, { "id": 1771737, "filename": "20160928.0602.00.bpk.rawacf.bz2", "checksum": null }, { "id": 1771737, "filename": "20160928.0602.00.bpk.rawacf.bz2", "checksum": null } ] List Single Instance of Small Transferred File with Given File Id +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Request:: GET /superdarn/mirror/v3/transferred/files/small/1771737?distinct=true HTTP/1.1 Host: api.bas.ac.uk:80 Accept: application/json Response:: HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 [ { "id": 1771737, "filename": "20160928.0602.00.bpk.rawacf.bz2", "checksum": null } ] Transfers --------- These are recorded instances of a transfer having occurred from a PI institute, or another SuperDARN Mirror node (see also `Transferred Files`_). URLs ^^^^ API calls are triggered by using the following URLs. .. csv-table:: :header: "Method", "Path", "Description" :widths: 6, 40, 50 GET, /superdarn/mirror/v3/transfers, "Lists all transfers, irrespective of whether an alarm condition occurred or not." GET, /superdarn/mirror/v3/transfers/:id, "Lists the transfer with id ``id``." GET, /superdarn/mirror/v3/transfers/ok, "Lists all transfers that completed without an alarm condition occurring." GET, /superdarn/mirror/v3/transfers/ok/:id, "Lists the ok transfer with id ``id``." GET, /superdarn/mirror/v3/transfers/alarm, "Lists all transfers that had any alarm condition occur." GET, /superdarn/mirror/v3/transfers/alarm/:id, "Lists the alarmed transfer with id ``id``." Examples ^^^^^^^^ List All Transfers for Given Timespan +++++++++++++++++++++++++++++++++++++ Request:: GET /superdarn/mirror/v3/transfers?timespan=2017-01-01T00:00:00/2017-01-01T23:59:59 HTTP/1.1 Host: api.bas.ac.uk:80 Accept: application/json Response:: HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 [ { "id": 13558, "transfer_log_file_path": "/home/superdarn/logs/acquisition/acquire_san_data_from_sanae.sh.log", "transfer_log_checksum": "6528676e142afa9feb4fb533a2af695997cbb3c9", "radar_code": "san", "start_datetime": "2017-01-01T00:10:01.000Z", "end_datetime": "2017-01-01T00:10:42.000Z", "duration": 41, "size": "105355638", "rate": 2601380, "method": "rsync", "is_error": false }, ... { "id": 13572, "transfer_log_file_path": "/home/superdarn/logs/acquisition/acquire_ksr_data_from_nict.sh.log", "transfer_log_checksum": "6bc473abb3b19972a232cb94d2cf4337dd03f7f8", "radar_code": "ksr", "start_datetime": "2017-01-01T20:00:01.000Z", "end_datetime": "2017-01-01T20:01:07.000Z", "duration": 66, "size": "330281985", "rate": 4966650, "method": "rsync", "is_error": false } ] Radars ------ These are the radars that make up the SuperDARN network. URLs ^^^^ API calls are triggered by using the following URLs. .. csv-table:: :header: "Method", "Path", "Description" :widths: 6, 40, 50 GET, /superdarn/mirror/v3/radars, "Lists all radars." GET, /superdarn/mirror/v3/radars/:id, "Lists the radar with id ``id``." By default, these calls will return a simple view which consists of the record's id, the ``hdw.dat`` filename and its checksum. Use the ``expanded`` query parameter to see the full record for a radar. Note that ``id`` is the database primary key, *not* the SuperDARN community allocated Radar ID - that field is called ``radar_id``. Examples ^^^^^^^^ List All Radars +++++++++++++++ Request:: GET /superdarn/mirror/v3/radars HTTP/1.1 Host: api.bas.ac.uk:80 Accept: application/json Response:: HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 [ { "id": 15, "filename": "hdw.dat.ade", "checksum": "514a742fe43c8c5c3fe8a030c1d0d52d431defd2" }, { "id": 16, "filename": "hdw.dat.adw", "checksum": "f7a3d6933592ba8495d6d09b1b9f41b2c76a1d6c" }, ... { "id": 14, "filename": "hdw.dat.zho", "checksum": "ca5954db83c18e2afd46bf43056638b0fc95ea22" } ] List Expanded View of Radars That Came Online During Given Timespan +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Request:: GET /superdarn/mirror/v3/radars?expanded=true×pan=2010-01-01/2014-12-31T23:59:59 HTTP/1.1 Host: api.bas.ac.uk:80 Accept: application/json Response:: HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 [ { "id": 15, "radar_id": 209, "radar_name": "Adak East", "radar_code": "ade", "radar_short_code": null, "geographic_position": { "type": "Point", "coordinates": [ -176.63, 51.89 ] }, "field_of_view": { "type": "Polygon", "coordinates": [ [ [ -784647.066586836, 771948.955098347 ], ... [ -784647.066586836, 771948.955098347 ] ] ] }, "country_name": "United States", "country_iso_code": "US", "institute_name": "University of Alaska, Fairbanks", "hdw_checksum": "514a742fe43c8c5c3fe8a030c1d0d52d431defd2", "hdw_file_path": "/home/superdarn/hdw_files/hdw.dat.ade", "earliest_data": "2012-09-08T17:25:56.000Z", "latest_data": "2017-05-31T22:01:00.000Z", "status_flag": 0 }, ... { "id": 14, "radar_id": 19, "radar_name": "Zhongshan Station", "radar_code": "zho", "radar_short_code": null, "geographic_position": { "type": "Point", "coordinates": [ 76.378, -69.379 ] }, "field_of_view": { "type": "Polygon", "coordinates": [ [ [ 5127385.32379075, -1484343.0959738 ], ... [ 5127385.32379075, -1484343.0959738 ] ] ] }, "country_name": "Antarctica", "country_iso_code": "AQ", "institute_name": "Polar Research Institute of China", "hdw_checksum": "ca5954db83c18e2afd46bf43056638b0fc95ea22", "hdw_file_path": "/home/superdarn/hdw_files/hdw.dat.zho", "earliest_data": "2010-04-03T12:01:53.000Z", "latest_data": "2017-04-30T22:01:00.000Z", "status_flag": 0 } ] List Expanded View of All Southern Hemisphere Radars ++++++++++++++++++++++++++++++++++++++++++++++++++++ Request:: GET /superdarn/mirror/v3/radars?expanded=true&bbox=-180,-90,180,0 HTTP/1.1 Host: api.bas.ac.uk:80 Accept: application/json Response:: HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 [ { "id": 4, "radar_id": 24, "radar_name": "Buckland Park", "radar_code": "bpk", "radar_short_code": null, "geographic_position": { "type": "Point", "coordinates": [ 138.46, -34.62 ] }, "field_of_view": { "type": "Polygon", "coordinates": [ [ [ 1987164.84456147, -2194271.34430221 ], ... [ 1987164.84456147, -2194271.34430221 ] ] ] }, "country_name": "Australia", "country_iso_code": "AU", "institute_name": "La Trobe University", "hdw_checksum": "39fd63ac54188a46dd1ea706b7ea03860159aa80", "hdw_file_path": "/home/superdarn/hdw_files/hdw.dat.bpk", "earliest_data": "2014-01-13T23:50:41.000Z", "latest_data": "2017-05-31T22:01:00.000Z", "status_flag": 0 }, ... { "id": 14, "radar_id": 19, "radar_name": "Zhongshan Station", "radar_code": "zho", "radar_short_code": null, "geographic_position": { "type": "Point", "coordinates": [ 76.378, -69.379 ] }, "field_of_view": { "type": "Polygon", "coordinates": [ [ [ 5127385.32379075, -1484343.0959738 ], ... [ 5127385.32379075, -1484343.0959738 ] ] ] }, "country_name": "Antarctica", "country_iso_code": "AQ", "institute_name": "Polar Research Institute of China", "hdw_checksum": "ca5954db83c18e2afd46bf43056638b0fc95ea22", "hdw_file_path": "/home/superdarn/hdw_files/hdw.dat.zho", "earliest_data": "2010-04-03T12:01:53.000Z", "latest_data": "2017-04-30T22:01:00.000Z", "status_flag": 0 } ] Temporal Coverage ----------------- These are contiguous intervals of data availability for a given radar. When filtering on a given timespan, those temporal coverage objects are returned whose interval (``start_datetime``, ``end_datetime``) *overlaps* with the timespan. URLs ^^^^ API calls are triggered by using the following URLs. .. csv-table:: :header: "Method", "Path", "Description" :widths: 6, 40, 50 GET, /superdarn/mirror/v3/coverage/temporal, "Lists all temporal coverage objects." GET, /superdarn/mirror/v3/coverage/temporal/:id, "Lists the temporal coverage object with id ``id``." Examples ^^^^^^^^ List All Temporal Coverage for Given Timespan +++++++++++++++++++++++++++++++++++++++++++++ Request:: GET /superdarn/mirror/v3/coverage/temporal?timespan=2016-01-01T00:00:00/2016-12-31T23:59:59 HTTP/1.1 Host: api.bas.ac.uk:80 Accept: application/json Response:: HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 [ { "id": 2106, "radar_code": "sto", "file_type": "RAWACF", "coverage_type": "File", "start_datetime": "2015-07-10T12:48:30.000Z", "end_datetime": "2016-01-05T00:00:00.000Z", "duration": 15419490, "status_flag": 0 }, { "id": 2191, "radar_code": "adw", "file_type": "RAWACF", "coverage_type": "File", "start_datetime": "2015-07-26T06:14:02.000Z", "end_datetime": "2016-02-16T00:00:00.000Z", "duration": 17689558, "status_flag": 0 }, ... { "id": 26656, "radar_code": "inv", "file_type": "RAWACF", "coverage_type": "File", "start_datetime": "2016-12-31T22:25:01.000Z", "end_datetime": "2017-01-01T00:00:00.000Z", "duration": 5699, "status_flag": 0 } ] Metadata -------- These are supporting metadata, such as the list of PI institutes, the list of radar/institute countries, data types used within the catalogue etc. These are probably of most use to applications that are built on the API. URLs ^^^^ API calls are triggered by using the following URLs. .. csv-table:: :header: "Method", "Path", "Description" :widths: 6, 40, 50 GET, /superdarn/mirror/v3/metadata/institutes, "Lists all PI institutes." GET, /superdarn/mirror/v3/metadata/institutes/:id, "Lists the PI institute with id ``id``." GET, /superdarn/mirror/v3/metadata/countries, "Lists all radar/institute countries." GET, /superdarn/mirror/v3/metadata/countries/:id, "Lists the radar/institute country with id ``id``." GET, /superdarn/mirror/v3/metadata/file/types, "Lists all file types." GET, /superdarn/mirror/v3/metadata/file/types/:id, "Lists the file type with id ``id``." GET, /superdarn/mirror/v3/metadata/coverage/temporal/types, "Lists all temporal coverage types." GET, /superdarn/mirror/v3/metadata/coverage/temporal/types/:id, "Lists the temporal coverage type with id ``id``." GET, /superdarn/mirror/v3/metadata/file/status, "Lists all file status objects." GET, /superdarn/mirror/v3/metadata/file/status/:id, "Lists the file status object with id ``id``." GET, /superdarn/mirror/v3/metadata/transferred/file/status, "Lists all transferred file status objects." GET, /superdarn/mirror/v3/metadata/transferred/file/status/:id, "Lists the transferred file status object with id ``id``." GET, /superdarn/mirror/v3/metadata/radar/status, "Lists all radar status objects." GET, /superdarn/mirror/v3/metadata/radar/status/:id, "Lists the radar status object with id ``id``." GET, /superdarn/mirror/v3/metadata/transfer/logs, "Lists all transfer log objects." GET, /superdarn/mirror/v3/metadata/transfer/logs/:id, "Lists the transfer log object with id ``id``." GET, /superdarn/mirror/v3/metadata/transfer/methods, "Lists all transfer methods." GET, /superdarn/mirror/v3/metadata/transfer/methods/:id, "Lists the transfer method with id ``id``." Examples ^^^^^^^^ List All PI Institutes ++++++++++++++++++++++ Request:: GET /superdarn/mirror/v3/metadata/institutes HTTP/1.1 Host: api.bas.ac.uk:80 Accept: application/json Response:: HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 [ { "id": 11, "institute_name": "British Antarctic Survey", "country_name": "Great Britain", "country_iso_code": "GB" }, { "id": 6, "institute_name": "CNRS/LPCE", "country_name": "France", "country_iso_code": "FR" }, ... { "id": 10, "institute_name": "Virginia Tech", "country_name": "United States", "country_iso_code": "US" } ] List All File Types +++++++++++++++++++ Request:: GET /superdarn/mirror/v3/metadata/file/types HTTP/1.1 Host: api.bas.ac.uk:80 Accept: application/json Response:: HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 [ { "id": 2, "file_type": "DAT", "file_format": "%Y%m%d%H%r*.dat" }, { "id": 1, "file_type": "RAWACF", "file_format": "%Y%m%d.%H%M.%S.%R*.rawacf" } ] List All Transfer Logs ++++++++++++++++++++++ Request:: GET /superdarn/mirror/v3/metadata/transfer/logs HTTP/1.1 Host: api.bas.ac.uk:80 Accept: application/json Response:: HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 [ { "id": 2, "file_path": "/home/superdarn/logs/acquisition/acquire_ade_mirror_data_from_usask.log", "checksum": "d77e572e081c741b9b3e16edd741545fb56b8a2a", "radar_code": "ade", "radar_name": "Adak East", "institute_name": "University of Alaska, Fairbanks" }, { "id": 3, "file_path": "/home/superdarn/logs/acquisition/acquire_adw_mirror_data_from_usask.log", "checksum": "5bf73886851da45f4efcf8d6d29ff1d0ab5a389f", "radar_code": "adw", "radar_name": "Adak West", "institute_name": "University of Alaska, Fairbanks" }, ... { "id": 33, "file_path": "/home/superdarn/logs/acquisition/acquire_zho_data_from_upload_area.sh.log", "checksum": "45e719b86313e8019a77fd3321269a631c069151", "radar_code": "zho", "radar_name": "Zhongshan Station", "institute_name": "Polar Research Institute of China" } ] .. |api_formal_title| replace:: SuperDARN Mirror Catalogue API .. |api_host_fqdn| replace:: api.bas.ac.uk:80