NAV
shell

Introduction

Welcome to the Constellation Scheduling API documentation. This service provides access to Spire's schedulers for payload operation scheduling.

This documentation includes examples in Bash. You can view code examples in the dark area to the right.

Authentication

Check Service Health

export HOST=https://api.scheduling.spire.com
http GET $HOST/api/v1/health Authorization:"Bearer YOUR_TOKEN_HERE"

Response

---
version: 1.10.2
system_time: "2021-02-24T10:55:42.666314649Z"
pending_plans: 0

The service uses API tokens to allow access to the API. If you do not have an API token then please reach out to support.

The API key should be included with every request through the Authorization header.

Authorization: Bearer YOUR_TOKEN_HERE

If you do not include an Authorization header then the service will return a 401 Unauthorized response. If the token provided is not valid then the service will also return a 401 Unauthorized response.

Service Health

Check Service Health

export HOST=https://api.scheduling.spire.com
http GET $HOST/api/v1/health

Response

---
version: 1.10.2
system_time: "2021-02-24T10:55:42.666314649Z"
pending_plans: 0

This endpoint gives general service information useful for health checks. A 200 response from this endpoint generally indicates that the service is available and ready for new jobs.

HTTP Request

GET /api/v1/health

Scheduling Jobs

The service currently supports the following schedulers:

Create a new job

Create a new job

export HOST=https://api.scheduling.spire.com
http -F POST $HOST/api/v1/payload_plan @problem.yaml

The above will perform a 303 See Other redirect to the job status page.

---
id: 4e7d1f4d-8832-47e4-a369-ae74463e7293
created_at: "2020-09-14T10:35:00.758876Z"
created_by: scheduling_user@spire.com
status: IN_PROGRESS
queue: simulation
plan_type: PAYLOAD

This endpoint allows you to create a new scheduling job from a constellation model file in YAML format.

If the file is valid and a job is created, the service will respond with 303 See Other and include the Location header for the corresponding job status endpoint. If your client is configured to follow redirects it should automatically redirect and return the job status.

A successful response indicates that the job has been placed in the work queue. If the queue is not empty it may take a non-negligible period of time to start solving your problem. The current length of the work queue is returned by the health endpoint.

HTTP Request

POST /api/v1/<PLAN_TYPE>

URL Parameters

Parameter Description
PLAN_TYPE payload_plan

List jobs

List jobs

export HOST=https://api.scheduling.spire.com
http $HOST/api/v1/payload_plan?limit=2

Response

---
- id: 805c045d-9b88-48dd-af9f-0a477aae9db6
  created_at: "2021-02-15T12:32:11.270385Z"
  created_by: scheduling_user@spire.com
  status: SUCCESS
  queue: simulation
  plan_type: PAYLOAD
- id: 6bc9838c-b23b-478f-99b3-16638846e01f
  created_at: "2021-02-15T00:32:10.111134Z"
  created_by: scheduling_user@spire.com
  status: SUCCESS
  queue: simulation
  plan_type: PAYLOAD

Use this endpoint to return a list of previously created jobs. Jobs will be returned in chronological order with the newest jobs returned first.

HTTP Request

GET /api/v1/<PLAN_TYPE>

URL Parameters

Parameter Description
PLAN_TYPE payload_plan

Query Parameters

Parameter Description
queue Only return jobs in this work queue
limit The number of jobs to return
status Only return jobs with this status

Get a job's status

Check Job Status

export HOST=https://api.scheduling.spire.com
export JOB_ID=4e7d1f4d-8832-47e4-a369-ae74463e7293
http $HOST/api/v1/payload_plan/$JOB_ID

Response

---
id: 4e7d1f4d-8832-47e4-a369-ae74463e7293
created_at: "2020-09-14T10:35:00.758876Z"
created_by: scheduling_user@spire.com
status: IN_PROGRESS
queue: simulation
plan_type: PAYLOAD

Use this endpoint to check a planning job's status. Jobs can take a long time to complete; polling the status page is the best way to check for completion.

HTTP Request

GET /api/v1/<PLAN_TYPE>/<ID>

URL Parameters

Parameter Description
ID The ID of the job to retrieve
PLAN_TYPE payload_plan

Get a job's result

Get Job Result

export HOST=https://api.scheduling.spire.com
export JOB_ID=4e7d1f4d-8832-47e4-a369-ae74463e7293
http $HOST/api/v1/payload_plan/$JOB_ID/result

Successful Plan Response (Constellation Model):

---
satellite:
  my_sat_1:
    payloads:
      death_ray:
        schedule:
          - start: "2020-09-14T10:35:00.758876Z"
            end: "2021-02-24T10:55:42.666314Z"
...

Failed Plan Response:

---
some yaml goes here # todo: fix

A completed job's output can be retrieved using this endpoint. In the event of a job failing to produce a schedule this endpoint will instead return a summary of the errors encountered.

HTTP Request

GET /api/v1/<PLAN_TYPE>/<ID>/result

URL Parameters

Parameter Description
ID The ID of the job to retrieve
PLAN_TYPE payload_plan

Get a job's solve information

Get Solve Info

export HOST=https://api.scheduling.spire.com
export JOB_ID=4e7d1f4d-8832-47e4-a369-ae74463e7293
http $HOST/api/v1/payload_plan/$JOB_ID/solve_info

The above command returns the job's solve_info in YAML format.

---
optimization_stats:
    constraints: 10
    variables: 10
    objective_value: 1.0
    optimality_gap: 2
    total_solve_time: "5s"
...

A completed job's solve information can be retrieved using this endpoint. The information provided by this endpoint is metadata for the solution that cannot be calculated from the result file. This is useful for examining the underlying optimization problem details.

HTTP Request

GET /api/v1/<PLAN_TYPE>/<ID>/solve_info

URL Parameters

Parameter Description
ID The ID of the job to retrieve
PLAN_TYPE payload_plan

Get a job's planning problem

Get a planning problem

export HOST=https://api.scheduling.spire.com
export JOB_ID=4e7d1f4d-8832-47e4-a369-ae74463e7293
http $HOST/api/v1/payload_plan/$JOB_ID/problem

Response:

---
model:
  goals:
    COLLECT_AIS:
      coverage:
        content:
...

The planning problem for a given job can be retrieved using this endpoint. This is useful in the case of workflows that need access to the model used for a previous job, such as for A/B comparative simulations.

HTTP Request

GET /api/v1/<PLAN_TYPE>/<ID>/problem

URL Parameters

Parameter Description
ID The ID of the job to retrieve
PLAN_TYPE payload_plan

Cancel a pending job

Cancel a job

export HOST=https://api.scheduling.spire.com
export JOB_ID=4e7d1f4d-8832-47e4-a369-ae74463e7293
http POST $HOST/api/v1/payload_plan/$JOB_ID/cancel

If the job can be cancelled, the above command will return a 200 response with no body. Otherwise, it will return a 400 response.

This endpoint allows job cancellation. Jobs which have already completed cannot be cancelled.

HTTP Request

POST /api/v1/<PLAN_TYPE>/<ID>/cancel

URL Parameters

Parameter Description
ID The ID of the job to cancel
PLAN_TYPE payload_plan

Errors

The SPORE API uses the following error codes:

Error Code Meaning
400 Bad Request The request is not valid due to a failed format check or the operation cannot be performed.
401 Unauthorized The request either did not include an Authorization header or the supplied API token was invalid.
403 Forbidden You do not have sufficient permission to perform the requested action.
404 Not Found The requested item could not be found.
500 Internal Server Error The server has encountered a problem. Try again later.

Constellation Models

Full Constellation Model Example

---
# Problem file schema
# currently only supports `v1`
version: v1

# The scheduling service job queue to use
# currently only `simulation` is supported
queue: simulation

# input model problem data
model:
   # type of input model
   # must be `unified`
   type: unified

   parameters:
     model_from: '2021-01-01T12:00:00Z'
     schedule_from: '2021-01-01T12:00:00Z'
     schedule_duration: 1day
     output_extended_metrics: false
     contact:
       data_chunk_build_time: 1m
       data_chunk_validity_period: 1day
       min_intercontact_time: 3m
       transit_split_ratio: 0.5
       min_download_duration: 2m
       min_transit_size: 1m 30s
     payload:
       earth_discretization: 10000
       time_discretization: 15m
       orbit_sample_rate: 1m
       drip_heuristic:
         satellites_per_run: 1
         optimize_heuristic_solution: true

   goals:
     OBSERVE_EARTH:
       downlink:
         downlink_pts: 1000
         latency_bonuses: {}
       capture:
         revisit_rate: 2hours
         first_visit_pts: 5
         revisit_pts: 2
         coverage: {type: global}
     OBSERVE_HAWAII:
       downlink:
         downlink_pts: 2000
         latency_bonuses:
           30mins: 10000
           2hours: 5000
       capture:
         revisit_rate: 2hours
         first_visit_pts: 10
         revisit_pts: 1
         coverage:
           type: aoi
           content:
             {"features":
                [{"geometry":
                    {"coordinates": [[[-150.5, 19.6],
                                      [-153.7, 26.5],
                                      [-162.8, 26.8],
                                      [-170.7, 18.6],
                                      [-165.1, 12.9],
                                      [-153.9, 14.6],
                                      [-150.5, 19.6]]],
                     "type": "Polygon"},
                  "properties":
                    {"name": "Hawaii",
                     "points_multiplier": 2.25},
                  "type": "Feature"}],
              "type": "FeatureCollection"}

   satellites:
     SAT_1:
       comms:
         BIDIRECTIONAL_COMMS:
           allowed_license_countries:
           - US
           constraints: {}
           contact_overhead_time: 3m 30s
           directionality: Bidirectional
           enabled: true
           goodput_kbps: 100.00
         SPACE_TO_EARTH_COMMS:
           allowed_license_countries:
           - US
           constraints:
             separation:
               - distance_m: 150000
                 tle: |
                      0 ISS (ZARYA)
                      1 25544U 98067A   21005.65916024  .00000359  00000-0  14531-4 0  9996
                      2 25544  51.6457  66.6353 0000701 180.7350 316.4489 15.49254565263407
                 type: minimum_distance
               - tle: |
                      0 ISS (ZARYA)
                      1 25544U 98067A   21005.65916024  .00000359  00000-0  14531-4 0  9996
                      2 25544  51.6457  66.6353 0000701 180.7350 316.4489 15.49254565263407
                 type: no_overlapping_transits
           contact_overhead_time: 30s
           directionality: SpaceToEarth
           enabled: true
           goodput_kbps: 200.0
       constraints:
         allow_consecutive_rxo: false
         allow_transit_splitting: true
         minimum_bidirs:
           amount: 4
           interval: 1day
       goals:
         non_production_target_time:
           points_per_second: 2.0
           time: 30min
       license_country: US
       payloads:
         EARTH_PAYLOAD:
           allow_contacts_while_active: true
           conflicting_payloads:
             - HAWAII_PAYLOAD
           data_rate_kbps: 10.0
           duty_ratio: 0.4
           duty_window: 8h
           footprint_radius_km: 1000
           goals:
           - OBSERVE_EARTH
           max_operational_time: 3h
           min_operational_time: 1h
           schedule:
             - start: '2021-01-01T20:00:00Z'
               end: '2021-01-01T22:00:00Z'
               external_id: EXISTING_PAYLOAD
         HAWAII_PAYLOAD:
           allow_contacts_while_active: true
           conflicting_payloads:
             - EARTH_PAYLOAD
           data_rate_kbps: 5.0
           duty_ratio: 0.2
           duty_window: 8h
           footprint_radius_km: 2000
           goals:
             - OBSERVE_HAWAII
           max_operational_time: 30min
           min_operational_time: 0min
           schedule:
             - start: '2021-01-01T15:00:00Z'
               end: '2021-01-01T15:15:00Z'
               external_id: EXISTING_PAYLOAD
       tle: |
            0 LEMUR 2 PETER
            1 40935U 15052F   21005.38409993  .00000920  00000-0  38119-4 0  9994
            2 40935   6.0056 328.9594 0011023 265.7591  94.1277 14.77380745285159

   ground_stations:
     CENTRAL_GS:
       location:
         elevation_m: 10.0
         latitude: 0.0
         longitude: 0.0
       comms:
         BIDIRECTIONAL_COMMS:
           allowed_license_countries:
           - US
           constraints:
             min_elevation_deg: 10.0
           contact_overhead_time: 30s
           directionality: Bidirectional
           enabled: true
           goodput_kbps: 100.0
         SPACE_TO_EARTH_COMMS:
           allowed_license_countries:
           - US
           constraints:
             min_elevation_deg: 25.0
           contact_overhead_time: 30s
           directionality: SpaceToEarth
           enabled: true
           goodput_kbps: 200.0
       constraints:
         blackout_periods:
           - start: '2021-01-01T18:00:00Z'
             end: '2021-01-01T19:00:00Z'
         max_slew_time: 30s
         min_schedule_horizon: 0s
       license_country: US

   contact_schedule:
     SAT_1:
       - start: '2020-01-01T12:00:00Z'
         end: '2020-01-01T12:10:00Z'
         external_id: Existing_Window
         dest: CENTRAL_GS
         channel_id: BIDIRECTIONAL_COMMS
       - start: '2020-01-01T13:00:00Z'
         end: '2020-01-01T13:10:00Z'
         external_id: Existing_Window
         dest: CENTRAL_GS
         channel_id: SPACE_TO_EARTH_COMMS

All of the services' schedulers operate on constellation models. Using a single format for problem input and output makes interchange between different schedulers simple and allows a user to compose the schedulers to fit their use case. The schema is documented below, with a representative example file.

Data Types

Constellation Models are defined using YAML, special value type schemas are defined below.

DateTime

All dates and times should comply with RFC 3339. All values will be converted to UTC on model serialization.

Example: 2020-12-22T19:37:23Z

Duration

Time durations are expected to be specified as humantime formatted strings.

Examples:

GeoJSON

Geographic features, such as Areas of Interest should be defined using GeoJSON. As YAML is a strict super-set of JSON, this field can use either JSON or YAML formatted data.

GeoJSON.io is a great tool for constructing and visualizing FeatureCollections.

Requirements:

Example GeoJSON Area of Interest:

{
    "features": [
        {
            "geometry": {
                "coordinates": [
                    [
                        [-150.5, 19.6],
                        [-153.7, 26.5],
                        [-162.8, 26.8],
                        [-170.7, 18.6],
                        [-165.1, 12.9],
                        [-153.9, 14.6],
                        [-150.5, 19.6]
                    ]
                ],
                "type": "Polygon"
            },
            "properties": {
                "name": "Hawaii",
                "points_multiplier": 2.25
            },
            "type": "Feature"
        }
    ],
    "type": "FeatureCollection"
}

Country Code

Country codes are defined using the ISO 3166 standard. Specifically we use the two character country code defined here

Example: US

Directionality

Directionality is an enumeration type of specific string values.

Values:

Solution Strategy

Solution Strategy may be defined as one of the following values:

Frequently Asked Questions

Schedule Optimality Guarantees

The service does not provide any guarantees of optimality for the schedules it produces. While no guarantee is provided, the scheduling engine will aim to be within 2% of the global optimal given the job is able to complete within its allocated time allowance.

Job Compute Time Allocation

All scheduling jobs have an associated compute time allowance. If a job exceeds this time allowance before finding a suitable solution then the best feasible solution found up to that point will be returned. The service will return an error if no feasible solution has been found within the time limit.

If you are regularly running into job timeouts then please reach out to us.

Job Repeatability

The scheduling engine is nondeterministic. Multiple runs with the same input scenario may not yield the same result.

Rate Limits

A rate limit of 120 requests per minute is enforced by the service, please ensure polling for job completion is performed with a sufficient delay in between requests.

shell