+ SPDF HOME

+ MISSION DATA

+ ModelWeb at CCMC

+ SCIENCE ENABLED

+ AND MORE

JSON with the SSC RESTful Web Services

Introduction

The following contains additional information concerning the use of JSON with the SSC web services.

Target Audience

This document assumes that the reader is familar with the SSC web services and JSON.

Overview

The official interface to the SSC web services is defined by this page and this XML schema. This is a well defined interface and every effort is made to maintain backward compatibility in future releases. Client developers who want maximum stability should use XML to interface with the SSC web services. However, JSON is supported as an alternative. Anyone choosing to use JSON should realize that it is less stable and may change in the future. There are also some limitations and peculiarities that a client developer must be aware of. The rest of this document describes these issues and contains some working examples of using JSON with the SSC web services.

Limitations

The following are limitations when using JSON which are not present when using XML:

• It is not possible to request magnetic field line tracing. That is, a DataRequest cannot include DataRequest/OutputOptions/BFieldTraceOptions ({"OutputOptions": {"BfieldTraceOptions": ...). If a client needs magnetic field line tracing, they must use XML to make the request.

Peculiarities

There are many detailed formatting issue with a JSON request that a client must follow. The details generally have to do with additional typing information that must be included in the JSON. For example, see the [ "gov.nasa.gsfc.sscweb.schema.Tsyganenko89CBFieldModel, ...]" and "java.util.ArrayList" fields in the following JSON fragment:

{
    "BfieldModel": {
        "ExternalBFieldModel": [
            "gov.nasa.gsfc.sscweb.schema.Tsyganenko89CBFieldModel",
            {   
                "KeyParameterValues": "KP_3_3_3"
            }   
        ],  
        "InternalBFieldModel": "IGRF",
        "TraceStopAltitude": 100
    },
    "Description": "Complex locator request with nearly all options.",
    "FormatOptions": null,
    "LocationFilterOptions": null,
    "OutputOptions": {
        "AllLocationFilters": true,
        "CoordinateOptions": [
            "java.util.ArrayList",
            [
                {
                    "Component": "X",
                    "CoordinateSystem": "GSE",
                    "Filter": null
                },
   ...

The easiest way to determine what a JSON request should be is to POST the equivalent XML request to /echoDataRequest, /echoGraphRequest, or /echoConjunctionRequest and request JSON for the response. For example, if you create an XML DataRequest in a file named dataRequest.xml. Then do

$ curl -H "Content-Type: application/xml" -H "Accept: application/json" \
    --data-ascii @dataRequest.xml \
    http://sscweb.gsfc.nasa.gov/WS/sscr/2/echoDataRequest \
    | python -mjson.tool > dataRequest.json

Next, edit dataRequest.json and change the "java.util.GregorianCalendar" field names in the "TimeInterval" object to "javax.xml.datatype.XMLGregorianCalendar". Now, dataRequest.json contains a JSON request that can be used with the SSC web services. Alternatively, you can examine the examples below.

Examples

The following section contains JSON examples of each type of SSC request. They illustrate how to use JSON to interact with the SSC web services.

Location Example

The following illustrates an SSC /locations request. The request entity body is

and the response is

Graph Example

The following illustrates an SSC /graphs request. The request entity body is

and the response is

Conjunction Example

The following illustrates an SSC /conjuctions request. The request entity body is

and the response is

Questions/Comments

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