Recent Additions to the OPUS API (/opus/api/metadata_v2)

The /opus/api/metadata/<OPUSID>.json API has long had a problem. While you request specific metadata using the "cols=" argument with slug names such as "opusid" or "SURFACEGEOtitancenterdistance", the returned data structure uses different names for those fields. This makes matching the returned values to the requested values difficult (they are at least given in the same order). On top of that, the returned names can be ambiguous. Take, for example, the query:

https://tools.pds-rings.seti.org/opus/api/metadata/COISS_2111-1866071296_1866225122-N1866071296_1.json?cols=opusid,instrument,planet,target,time1,observationduration,SURFACEGEOsaturncenterdistance,SURFACEGEOtitancenterdistance

This returns:

[{"opus_id": "COISS_2111-1866071296_1866225122-N1866071296_1"},
 {"instrument_id": "COISS"},
 {"planet_id": "SAT"},
 {"target_name": "TITAN"},
 {"time1": "2017-048T23:59:39.059"},
 {"observation_duration": 46.0},
 {"center_distance": 272061.836},
 {"center_distance": 272061.836}
]

Even though we queried on, for example, "opusid", we were returned a field named "opus_id". Worse yet, we have two returned fields called "center_distance" without a way to disambiguate them (and they are incorrectly the same value).

A second problem is that some of the returned values, such as "COISS" or "SAT", are internal representations, not the values normally shown to the user such as "Cassini ISS" or "Saturn".

To fix these problems while still providing backwards compatibility, we have introduced a second version of this API:

/opus/api/metadata_v2/<OPUSID>.json

This version fixes all of the problems mentioned above. For example, the similar query:

https://tools.pds-rings.seti.org/opus/api/metadata_v2/COISS_2111-1866071296_1866225122-N1866071296_1.json?cols=opusid,instrument,planet,target,time1,observationduration,SURFACEGEOsaturncenterdistance,SURFACEGEOtitancenterdistance

returns:

[{"opusid": "COISS_2111-1866071296_1866225122-N1866071296_1"},
 {"instrument": "Cassini ISS"},
 {"planet": "Saturn"},
 {"target": "Titan"},
 {"time1": "2017-048T23:59:39.059"},
 {"observationduration": 46.0},
 {"SURFACEGEOsaturncenterdistance": 1284796.671},
 {"SURFACEGEOtitancenterdistance": 272061.836}
]

Note that the labels are the same as the requested slugs, and the values are the same as seen in the main OPUS web UI.

We strongly suggest that you use the new version of the metadata API going forward to avoid these problems.