SBDB Filter Parameters

Version: 1.0 (2021 August)
change log

Several SBDB-related APIs benefit by the ability to consider a filtered subset of the complete SBDB. This document details the common set of query parameters used in these APIs.

For more information about JPL’s SBDB, see this page from the SSD website.

Query Parameters

Note that all parameter names are prefixed with sb- to reduce the chance of name conflicts with other API query parameters.

Available SBDB Orbit Classes

Orbit class codes are listed in the table below, ordered by asteroids and increasing semimajor axis, then by comets. The “Kind” column indicates whether the class is generally associated with asteroids or comets. Those classes for which the object is not clearly associated with asteroids or comets is indicated with a blank value for “Kind”. Comet class names with a trailing * indicate a classical definition for that orbit class.

Orbit class codes are case-sensitive.

Orbit class descriptions above use the following symbols to indicate orbit parameters:

• e - eccentricity
• q - perihelion distance
• a - semimajor axis
• Q - aphelion distance
• P - orbital period
• Tj - Jupiter Tisserand parameter
• aJ - Jupiter nominal semimajor axis

Custom Field Constraints

Custom constraints provide a method of selecting only the objects of interest from the SBDB. A constraint is defined for a specific SBDB field using a variety of forms. For example, you might constrain the orbital inclination to be less than 8 degrees, constrain the orbital semimajor axis to be between 3.1 and 9.9 au, limit results to object for which a diameter is defined (i.e., exists in the SBDB), and/or match objects with a designation matching 2018 L*. A constraint operator relates the field with user-specified values (limits, ranges, flags). For example, the operator LT says the field value must be less than the user-specified value. Each constraint can be combined with other constraints using the appropriate logical operator (either a logical AND or a logical OR).

The sections below provide a list of fields available for constraint, a list of constraint operators, constraint format specification, and some examples.

Available SBDB Fields

The following tables list fields available for use in custom field constraints.

Field names are case-sensitive.

Physical Parameter Fields

Orbit and Model Parameter Fields

Orbit Determination Fields

Mission Design Fields

Characters Allowed in Constraint Values

• number fields: digits, decimal point ., sign - or + and exponent character e or E
• string fields: letters, digits, space, ., -, /, :, (, ), ' and `
• regular expressions: letters, digits, space, ., -, +, /, :, (, ), ^, $, \, *, [, ], ' and `

Operators

Constraint Format Specification (JSON)

The set of desired constraints are specified using the following JSON format. Examples of this constraint specification are given in the next section.

C-OBJ [, C-OBJ]…

• C-OBJ is a JSON object of the following form:

{ LOP : [ CON [, CON]…] }

• LOP is the logical operator string and must be either "AND" or "OR"
• CON is a valid constraint string of the following form:

"FIELD|OP[|VALUE[|VALUE2] ]"

• FIELD is a valid SBDB field name
• OP is a valid constraint operator (see table above)
• VALUE is the constraint value (must be specified unless OP does not require it, e.g., DF)
• VALUE2 is the second constraint value (only required for OP RG)

Examples

Example: complex set of constraints

Consider the following query where the desired set of small-bodies are constrained as follows.

1. spectral class is C or D (include full C-complex types and D-complex types, e.g. C as well as CDX:)
   • each of these constraints can be accomplished with regular expressions
   • spec_B matches ^[CD] OR spec_T matches ^[CD] ( where ^[CD] matches any string starting with C or D )
2. at least one of the three broadband color measurements is available (BV, UB, or IR)
   • BV IS DEFINED OR UB IS DEFINED OR IR IS DEFINED
3. orbital inclination is less than 10.5 degrees
   • i<10.5
4. H is between 6 and 7 (inclusive)
   • 6<=H<=7
5. either a diameter or an albedo with H is available
   • diameter IS DEFINED OR (albedo IS DEFINED AND H IS DEFINED)

Each of these four conditions must be met which implies they should be combined with a logical AND. Here is the JSON-form of the above constraints.

{
  "AND":[
    { "OR":["spec_B|RE|^[CD]","spec_T|RE|^[CD]"] },
    { "OR":["BV|DF","UB|DF","IR|DF"] },
    "i|LT|10",
    "H|RG|7|8",
    { "AND":["condition_code|EQ|0","source|EQ|ORB"] },
    { "OR":[ "diameter|DF",{ "AND":["albedo|DF","H|DF"] } ] }
  ]
}

Example: single constraint

In this example, limit results to small-bodies for which a rotation pole direction is available.

• pole IS DEFINED

The JSON format in this example is as follows.

{ "AND" : [ "pole|DF" ] }

Note that even though there is only one constraint, we still require a logical operator and a list of constraints. In this example, the logical operator is effectively ignored so "OR" works just as well as "AND".

URI Encoding

The constraint specification in JSON format must be converted into a URI-encoded string before being used in the API call. There are many tools available to convert an arbitrary string to a URI-encoded string.

Given this JSON-format constraint data

{ "AND" : [ "pole|DF" ] }

the corresponding URI-encoded string is as follows.

%7B%20%22AND%22%20%3A%20%5B%20%22pole%7CDF%22%20%5D%20%7D

With extraneous white-space removed (recommended best practice), the JSON becomes

{"AND":["pole|DF"]}

the corresponding URI-encoded string (as follows) is significantly shorter.

%7B%22AND%22%3A%5B%22pole%7CDF%22%5D%7D

Mode I: Definitions and Information

Container for all sections is sb_defs

Sample Output Sections:

"class" : [
  { "code" : "AMO",
    "kind" : "A",
    "title" : "Amor",
    "description" : "Near-Earth asteroid orbits similar to that of 1221 Amor (1.017 au < q < 1.3 au)."
  },
  { "code" : "PAR",
    "kind" : "C",
    "title" : "Parabolic Comet",
    "description" : "Comets on parabolic orbits (e = 1.0)."
  },
  ...
]

"field" : {
  "object" : {
    "field_label" : "Object Fields",
    "constraint_label" : null,
    "list" : [
      FIELD_INFO_RECORD,
      ...
    ]
  },
  "orbit" : {
    "field_label" : "Orbit and Model Parameter Fields",
    "constraint_label" : "Orbital Parameter",
    "list" : [
      FIELD_INFO_RECORD,
      ...
    ]
  },
  "phys_par" : {
    "field_label" : "Physical Parameter Fields",
    "constraint_label" : "Physical Parameter",
    "list" : [
      FIELD_INFO_RECORD,
      ...
    ]
  }

FIELD_INFO_RECORD example:

{
   "name" : "IR",
   "title" : "I-R",
   "description" : "color index I-R",
   "units" : "mag",
   "is_numeric" : "Y",
   "is_constraint" : "Y",
   "align_comp" : null,
   "align_full" : "C"
}

Regular Expressions RE

Regular expressions provide a subset of those specified in Henry Spencer’s implementation. See the regex(7) man-page for more details.

Only the characters from the following subset are allowed in regular expressions.

• digits [0-9]
• letters [A-Z] and [a-z]
• space ` `
• special characters: ^, $, ., *, ?, +, :, <, >, (, ), [, ], ', ` ``, /, \

Special characters and constructs:

Change Log

Version 1.0 (2021 August)

• Initial release