# SSC RESTful Web Services

## Introduction

NASA's Satellite Situation Center is a system to cast geocentric spacecraft location information into a framework of (empirical) geophysical regions and mappings of spacecraft locations along lines of the Earth's magnetic field. While SSCWeb provides access to this data through an HTML-based user interface, these Web services provides a (Web) application programmming interface (API) to SSC. If you are not a software developer and simply want to use the existing web (HTML) interface to SSC, then return to the main SSCWeb page. If you are developing software that requires the type of information available at SSC, then these SSC Web services will provide a convenient API to the information. This document is organized as follows:

- Simple Access Mechanisms
- Technical Details

### Simple Access Mechanisms

This section describes simple, high-level, mechanisms for accessing SSC data through these web services from various programming languages. If these do not meet your needs, you may be interested the low-level details instead.

- sscws is a Python module to easily access SSC data.
  - Getting started with the `sscws` client library.
  - sscws at
  - sscws at
  - Jupyter Notebook Examples:
    - Simple Location Example (ipynb file).
    - Complex Location Example (ipynb file) requesting many values including magnetic field line tracing. This example also demonstrates how to diagnose a problem with an invalid request.
    - Radial Conjunction With Ground Location (ipynb file).
    - Magnetic Field Line Conjunction Example (ipynb file) with related data retrieval/plotting using cdasws.
  - PyScript example of using sscws in a web page.
  - These web services themselves can produce example client Python and IDL® source code. For example, here is example client code to get International Space Station (ISS) orbit information.

- NV5 Interactive Data Language (IDL®)

- SPDF SSC IDL® Web Services Library. This library makes it easy to call these web services from IDL® code. The library contains several complete example clients (e.g., spdfsscwsexample) and an IDL® Jupyter notebook.

- Unix Shell Script
  - Shell Script Examples. These examples should run on most Unix-like (e.g., macOS, Linux, Solaris, Windows Subsystem for Linux, etc.) platforms that have `curl`, `xsltproc`, and `xmllint`. To install the prerequisite software on debian/ubuntu based Linux distributions, do
    - `$ sudo apt install libxml2-utils`
    - `$ sudo apt install xsltproc`
    To install the prerequisite software on rpm based Linux distributions, do
    - `$ sudo dnf install libxml2`
    - `$ sudo dnf install libxslt`
- JavaScript
  - Fetch API
  - jQuery .ajax()
- JavaScript Examples. These examples should run on most modern browsers.
  - Get Graphs example.
  - Get Locations example.
- Java
  - Jakarta RESTful Web Services client API
  - JAX-RS Examples
    - Java EE 8 Location example.
    - Jakarta EE 10 Location example.
    To run the Location examples, do the following:
    1. Download the version you want.
    2. untar the files.
    3. cd JaxRsExamples/java
    4. mvn compile
    5. mvn exec:java
    - Jakarta EE 10 Conjunction example.

## Technical Details

This section contains a more detailed description of the SSC web service interface. These details are only relevant if the high-level mechanisms described above are insufficient for your use. For example, if you are using a programming language other than Python, IDL, or Java. This section is organized as follows:

- Target Audience
- Overview
- Web Services

## Target Audience

This document assumes that the reader is familar with RESTful Web service and Hypertext Transfer Protocol (HTTP) technology.

## Overview

This section contains an overview of these Web services.

### Entity-Body Representations

The HTTP entity-body for both the request and response messages of these services is described by a W3C XML schema document (diagram). The detailed description of each service describes the specific XML element from the schema that is an entity-body for the specific request or response message of the service. In addition to the XML representation of the entity-body, all the services can return the entity-body in a mapped (with root unwrapping) JSON representation of the XML object. A client can express their preference for a specific entity-body representation (XML or JSON) by setting the HTTP accept header (to "application/xml" or "application/json").

JSON Support
Anyone considering using JSON, should read this page first.

### Error Responses

This section provides a general description of error responses (i.e., a reponse with a code other than 200) that may be returned by any of the web services. More details about the error response of specific services are provided in the specific service's description.
Any entity-body returned within an error response will be XHTML (or a JSON representation of XHTML) that contains a more detailed description of the error. Whether the entity-body is XHTML or JSON depends upon the HTTP Accept header in the request. Not all error responses will contain an entity-body. A client may simply display the XHTML or access the more detailed error message within the XHTML at `//p[class='ErrorMessage']/text() and` `//p[class='ErrorDescription']/text().`
Note that error responses may also be generated by software components other than the web services software described here in response to requests intended for these web services. For example, a request with an invalid URI path may result in a response (e.g., 404) that is generated by the application server instead of by the web service software. In fact, different invalid URI paths may result in an error response being generated by a proxy server, the application firewall, the web application server, the web service framework, or the web service implementation itself. The entity-body in an error response will vary depending upon the software component that generates the response. A client must be prepared to deal with these differences. The above description of an entity-body in an error response only describes those generated by the web service implementation itself. At the time this documentation was written, the entity-body returned in an error response from both these web services and the application server hosting them were similar. The `//p[class='ErrorMessage']/text()` value described above is accessible by`//p[2]/text()` in the error response from both these web services and their hosting application server. Likewise, the `//p[class='ErrorDescription']/text()` value described above is accessible by`//p[3]/text()` in the error response from both these web services and their hosting application server.

### Cross-Origin Resource Sharing

These web services implement the Cross-Origin Resource Sharing (CORS) mechanism and allow cross-origin access from any domain.

### Software Development Kit (SDK)

The SSC REST SDK consists of documentation, example code, and pre-compiled client libraries that may be helpful to client developers. The SDK is available for download here.

### Web Services

The table below summarizes the services which are available. Only the last part of the URL's path is shown in the table. The beginning part of the URL is
`https://sscweb.gsfc.nasa.gov/WS/sscr/2`
The table contains links to more detail descriptions of each operation.

Web Services
Category | Operation | Implementation | Details
--- | --- | --- | ---
Metadata | Get WADL | GET /application.wadl | Details
Get Observatories | GET /observatories | Details
Get Client Example | GET /observatories/{observatory}/clientLibraryExample/{library}?mediaType={mediaType} | Details
Get SPASE Observatories | GET /spaseObservatories | Details
Get GroundStations | GET /groundStations | Details
Data | Get Locations | POST /locations | Details
GET /locations/{observatories}/{timeRange}/{coordinateSystems}/ | Details
Get Graphs | POST /graphs | Details
Get Conjunctions | POST /conjunctions | Details

### Get WADL

This service provides the Web Application Description Language (WADL) for these Web services.

#### Example

Here is a request https://sscweb.gsfc.nasa.gov/WS/sscr/2/application.wadl for the WADL.

    $ curl https://sscweb.gsfc.nasa.gov/WS/sscr/2/application.wadl | xmllint --format -

### Get Observatories

This service provides descriptions of the observatories that are available from SSC. The following table describes the HTTP request and response.

HTTP Method | GET |
Partial Path | /observatories?id={id} |
Significant Request Headers | Accept | application/xml
application/json
If-None-Match |
Request Entity | none |
Significant Response Headers | ETag |
Cache-Control |
Response Entity | Content-Type: application/xml | As specified by ObservatoryResponse in SSC.xsd
Content-Type: application/json | JSON representation of ObservatoryResponse in SSC.xsd
Most Likely Response Codes | 200 | Ok
304 | Not Modified
406 | Not Acceptable

Where:

- {id} = observatory identifiers for which information is being requested. The values must be from those returned by Get Observatories. If no identifiers are given, all observatory descriptions are returned.

### Get Client Example

This service provides example client code to retrieve data for an observatory. The following table describes the HTTP request and response.

HTTP Method | GET |
Partial Path | /observatories/{observatory}/clientLibraryExample/{library}?mediaType={mediaType} |
Significant Request Headers | Accept | application/xhtml+xml
application/octet-stream
text/plain
text/x-python
text/x-idl
If-None-Match |
Request Entity | none |
Significant Response Headers | ETag |
Cache-Control |
Response Entity | Content-Type: application/xhtml+xml | An XHTML page containing example code for the specified client library to retrieve data for the specified observatory.
Content-Type: text/plain, text/x-python, text/x-idl, application/octet-stream | Example code for the specified client library to retrieve data for the specified observatory.
Most Likely Response Codes | 200 | Ok
304 | Not Modified
406 | Not Acceptable

### Notes:

- The path parameters are described below:

- The {observatory} value is one returned by Get Observatories.
- The {library} value is a comma separated list of these values: sscwsPy,sscwsIdl. If no {library} values are specified and the Accept HTTP header value indicates a peference for XHTML, then example code for all known libraries are included. If no {library} value is specified and the Accept HTTP header value is absent or indicates a preference for text/plain, the code is returned for the sscwsPy library.
- The optional {mediaType} query parameter overrides the HTTP Accept header value for those cases where it is difficult or impossible for the client to set the HTTP header. The valid values are as follows:

  Value | Corresponding MIME Type
  --- | ---
  octet | application/octet-stream
  plain | text/plain
  python | text/x-python
  idl | text/x-idl

### Get SPASE Observatories

This service provides descriptions of the observatories with SPASE ResourceIDs that are available from SSC. The following table describes the HTTP request and response.

HTTP Method | GET |
Partial Path | /spaseObservatories |
Significant Request Headers | Accept | application/xml
application/json
Request Entity | none |
Response Entity | Content-Type: application/xml | As specified by ObservatoryResponse in SSC.xsd
Content-Type: application/json | JSON representation of ObservatoryResponse in SSC.xsd
Most Likely Response Codes | 200 | Ok
406 | Not Acceptable

### Get Ground Stations

This service provides descriptions of the ground stations that are available from SSC. The following table describes the HTTP request and response.

HTTP Method | GET |
Partial Path | /groundStations |
Significant Request Headers | Accept | application/xml
application/json
If-Modified-Since |
Request Entity | none |
Significant Response Headers | Last-Modified |
Cache-Control |
Response Entity | Content-Type: application/xml | As specified by GroundStationDescription in SSC.xsd
Content-Type: application/json | JSON representation of GroundStationDescription in SSC.xsd
Most Likely Response Codes | 200 | Ok
304 | Not Modified
406 | Not Acceptable

### Get Locations (POST)

This service provides observatory location information. The following table describes the HTTP request and response.

HTTP Method | POST |
Partial Path | /locations |
Significant Request Headers | Accept | application/xml
application/json
Request Entity |  | As specified by DataRequest in SSC.xsd
Significant Response Headers | Last-Modified |
Response Entity | Content-Type: application/xml | As specified by DataResult in SSC.xsd
Content-Type: application/json | JSON representation of DataResult
Most Likely Reponse Codes | 200 | Ok
304 | Not Modified
404 | Not Found
406 | Not Acceptable
415 | Unsupported Media Type
429 | Too Many Requests. Check Retry-After header value.
503 | Service Unavailable. Check Retry-After header value.

### Get Locations (GET)

This service provides basic observatory location information. It is a simplified version of the Get Locations (POST) resource. It does not support all the features of the POST method. In particular, no values related to the magnetic field models (for example, distance to bowshock) are available with this method. The following table describes the HTTP request and response.

HTTP Method | GET |
Partial Path | /locations/{observatories}/{timeRange}/{coordinateSystems}/?resolutionFactor={resolutionFactor} |
Significant Request Headers | Accept | application/xml
application/json
Request Entity |  | None
Significant Response Headers | Last-Modified |
Response Entity | Content-Type: application/xml | As specified by DataResult in SSC.xsd
Content-Type: application/json | JSON representation of DataResult
Most Likely Reponse Codes | 200 | Ok
304 | Not Modified
404 | Not Found
406 | Not Acceptable
415 | Unsupported Media Type
429 | Too Many Requests. Check Retry-After header value.
503 | Service Unavailable. Check Retry-After header value.

Where:

- {observatories} = a comma separated list of observatory identifiers for which location data is being requested. The values must be from those returned by Get Observatories.
- {timeRange} = time range for which data location is being requested. There must be two comma separated basic format (minimal number of separators) ISO 8601 date values.
- {coordinateSystems} = a comma separated list of the names of the coordinate systems in which to represent the returned location information. The values must be from this list: `geo, gm, gse, gsm, sm, geitod, geij2000`. If no values are given, `gse` will be assumed. For each coordinate system, the X, Y, Z, Latitude, Longitude, and local-time (if applicable) values will be returned.
- {resolutionFactor} = Resolution factor. Include 1 out of every ResolutionFactor values.
- The `output=listing` query parameter value requests a file containing the location information in a more human readable form be produced instead of the XML/JSON entity body that is otherwise produced.

For example:

    $ curl -s https://sscweb.gsfc.nasa.gov/WS/sscr/2/locations/mms1,mms2/20190101T000000Z,20190101T001000Z/gse,geo/ | xmllint --format -

### Get Graphs (POST)

This service provides observatory location graphs. The following table describes the HTTP request and response.

HTTP Method | POST |
Partial Path | /graphs |
Significant Request Headers | Accept | application/xml
application/json
Request Entity |  | As specified by GraphRequest in SSC.xsd
Significant Response Headers | Last-Modified |
Response Entity | Content-Type: application/xml | As specified by LocationFileResult in SSC.xsd
Content-Type: application/json | JSON representation of LocationFileResult
Most Likely Reponse Codes | 200 | Ok
304 | Not Modified
404 | Not Found
406 | Not Acceptable
415 | Unsupported Media Type
429 | Too Many Requests. Check Retry-After header value.
503 | Service Unavailable. Check Retry-After header value.

### Get Conjunctions (POST)

This service provides results of a conjunction query. The following table describes the HTTP request and response.

HTTP Method | POST |
Partial Path | /conjunctions |
Significant Request Headers | Accept | application/xml
application/json
Request Entity |  | As specified by QueryRequest in SSC.xsd
Significant Response Headers | Last-Modified |
Response Entity | Content-Type: application/xml | As specified by QueryResult in SSC.xsd
Content-Type: application/json | JSON representation of QueryResult
Most Likely Reponse Codes | 200 | Ok
304 | Not Modified
404 | Not Found
406 | Not Acceptable
415 | Unsupported Media Type
429 | Too Many Requests. Check Retry-After header value.
503 | Service Unavailable. Check Retry-After header value.

###

## Questions/Comments

Questions or comments concerning these Web services should be sent to SSC Feedback.