API documentation

Back to main page

Overview

The status API has four endpoints:

• api/v1/getstatusall/byid returns a dictionary of all site statuses identified by site ID
• api/v1/getstatusall/byname returns a dictionary of all site statuses identified by site name
• api/v1/getstatus/byid/$SITEID returns the status for just the site identified by the given site ID
• api/v1/getstatus/byname/$NAME returns the status for just the site identified by the given name

Note, you can omit the "v1" component of the URL, but it is recommended to keep it (and update URLs that don't include it) so that future breaking API changes do not automatically affect you. Omitting the version in the URL will use the latest version of the API.

A status will have the following components:

• id: the two-letter site ID
• name: the site name
• status: the operational status, which will be "Yes" for operational, "No" for non-operational, and "Replaced/retired" if requesting a site by ID that has been superceded by a new ID (i.e. if a new instrument was installed at the same site).
• descr: The description of the current status provided by the site personnel. May be empty.
• user: The user who last updated the site status.
• date: The date that the status was updated, in YYYYMMDD format.
• display_descr: A string that combines descr, user, and date that can be displayed as a quick summary of the status.

Should you request a nonexistant site ID with api/getstatus/byid or name with api/getstatus/byname, the returned JSON will have a single field (error) and the status code will be 406.

Examples

1. Get all sites, identified by their site ID:

$ curl https://parkfalls.gps.caltech.edu/car/opstat/api/v1/getstatusall/byid

 {
  "ae": {
    "id": "ae",
    "name": "Ascension_Island",
    "status": "No",
    "descr": "Solar tracker dome failed. Unclear how this can be fixed under the current Covid-19 restrictions.",
    "user": "dfeist",
    "date": "20200813", "display_descr": "Solar tracker dome failed. Unclear how this can be fixed under the current Covid-19 restrictions. [dfeist 20200813]"
    },
  "an": {
    "id": "an",
    "name": "Anmyeondo",
    "status": "Yes",
    "descr": "Normal operation on August 19",
    "user": "y_soh",
    "date": "20200915",
    "display_descr": "Normal operation on August 19 [y_soh 20200915]"
    },
  "bi": {
    "id": "bi",
    "name": "Bialystok",
    "status": "No",
    "descr": "Dismounted on 2018/10/01. System will be moved to Cyprus/Greece, first measurements expected in February 2019",
    "user": "christof",
    "date": "20181001",
    "display_descr": "Dismounted on 2018/10/01. System will be moved to Cyprus/Greece, first measurements expected in February 2019 [christof 20181001]"
    },
  ...
}
        

2. Get all sites, identified by their site names:

$ curl https://parkfalls.gps.caltech.edu/car/opstat/api/v1/getstatusall/byname

{
  "Ascension_Island": {
    "id": "ae",
    "name": "Ascension_Island",
    "status": "No",
    "descr": "Solar tracker dome failed. Unclear how this can be fixed under the current Covid-19 restrictions.",
    "user": "dfeist",
    "date": "20200813",
    "display_descr": "Solar tracker dome failed. Unclear how this can be fixed under the current Covid-19 restrictions. [dfeist 20200813]"
    },
  "Anmyeondo": {
    "id": "an",
    "name": "Anmyeondo",
    "status": "Yes",
    "descr": "Normal operation on August 19",
    "user": "y_soh",
    "date": "20200915",
    "display_descr": "Normal operation on August 19 [y_soh 20200915]"
    },
  "Bialystok": {
    "id": "bi",
    "name": "Bialystok",
    "status": "No",
    "descr": "Dismounted on 2018/10/01. System will be moved to Cyprus/Greece, first measurements expected in February 2019",
    "user": "christof",
    "date": "20181001",
    "display_descr": "Dismounted on 2018/10/01. System will be moved to Cyprus/Greece, first measurements expected in February 2019 [christof 20181001]"
    },
  ...
}
        

3. Get one site (here, Park Falls) by its site ID:

$ curl https://parkfalls.gps.caltech.edu/car/opstat/api/v1/getstatus/byid/pa

{
    "id": "pa",
    "name": "Park_Falls",
    "status": "Yes",
    "descr": "(Fingers crossed) Still working fine!",
    "user": "coleen",
    "date": "20220222",
    "display_descr": "(Fingers crossed) Still working fine! [coleen 20220222]"
}
        

4. Get one site (here, Park Falls) by its site name:

$ curl https://parkfalls.gps.caltech.edu/car/opstat/api/v1/getstatus/byname/Park_Falls

{
    "id": "pa",
    "name": "Park_Falls",
    "status": "Yes",
    "descr": "(Fingers crossed) Still working fine!",
    "user": "coleen",
    "date": "20220222",
    "display_descr": "(Fingers crossed) Still working fine! [coleen 20220222]"
}
        

Back to main page