SSC RESTful Web Services

Introduction

The 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, the the 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 Package API

    • Getting started with the sscws client library.

    • sscws at the PyPI respository.

    • sscws at the

    • 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

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

Below is an example client request to this service and the results.

$ 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
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

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.