rocket-launch-live-client

Table of Contents

• Requirements
• Simple Usage
• Client Configuration
• Endpoints
  • Response Types
  • Companies
  • Launches
  • Locations
  • Missions
  • Pads
  • Tags
  • Vehicles
• Watcher
  • Methods and Properties
  • Options
  • Events

This package is a fully-typed, promise-based, zero-dependency Node.JS JavaScript/TypeScript library for interacting with the RocketLaunch.Live API.

Requirements

This package is tested on and supports Node 14.18 or higher. It is fully CommonJS/ESM compatible and has Typescript support built in.

Simple usage

1// Import package
2import { rllc } from "rocket-launch-live-client";
3
4// Get API Your Key
5const RLL_API_KEY = process.env.RLL_API_KEY;
6
7// Create client
8const client = rllc(RLL_API_KEY);
9
10// Call endpoints
11const launches = await client.launches();

Client Configuration

RLL Clients require an API key as the first parameter, and will throw if one is not present.

The client can be configured with an optional second parameter using the following keys:

1const options = {
2  // Defaults to false.
3  // API Key is normally passed in the Authorization Bearer header
4  // Set to true to pass your API key as a query parameter instead (not recommended)
5  keyInQueryParams: true,
6};
7
8const client = rllc(RLL_API_KEY, options);

Endpoints

All endpoints return the following response format, where T is an array of results:

1type RLLResponse<T> = {
2  errors?: string[];
3  valid_auth: boolean;
4  count: number;
5  limit: number;
6  total: number;
7  last_page: number;
8  result: T;
9};

All endpoints return a maximum of 25 results per page. A page argument can be passed to retrieve incremental results.

1const response = await client.launches({ page: 2 });
2// Also accepts page number as a number-parseable string like "2"

For complete API Documentation on parameters, be sure to visit RocketLaunch.Live

Response Types

All entity response types are browseable in the GitHub Repository.

Companies

1const response = await client.companies(options);

Optional search parameters:

1const options = {
2  // Company numeric id
3  // Also accepts number parseable strings like "1"
4  id: 1,
5
6  // Company name
7  name: "SpaceX",
8
9  // Company country
10  // ISO 3166 Alpha 2 Country Code
11  country_code: "US",
12
13  // For defunct companies
14  inactive: true,
15};

Launches

1const response = await client.launches(options);

Optional search parameters:

1const options = {
2  // Launch numeric id
3  // Also accepts number parseable strings like "1"
4  id: 1,
5
6  // COSPAR
7  // Format YYYY-NNN
8  cospar_id: "2022-123",
9
10  // Show launches only before this date
11  // JS Date Object - Anything more precise than day is ignored
12  // Also accepts any date string which can be used to create a valid Date object in JavaScript
13  before_date: new Date("2023-01-31"),
14
15  // Show launches only after this date
16  // JS Date Object - Anything more precise than day is ignored
17  // Also accepts any date string which can be used to create a valid Date object in JavaScript
18  after_date: new Date("2023-01-31"),
19
20  // Show launches that have had data updated since this date
21  // Useful for checking for changes since your last API call
22  // JS Date Object
23  // Also accepts any date string which can be used to create a valid Date object in JavaScript
24  modified_since: new Date("2023-01-31T06:00:00Z"),
25
26  // Launch location id
27  // Also accepts number parseable strings like "1"
28  location_id: 1,
29
30  // Launch pad id
31  // Also accepts number parseable strings like "1"
32  pad_id: 1,
33
34  // Launch provider id
35  // Also accepts number parseable strings like "1"
36  provider_id: 1,
37
38  // Launch tag id
39  // Also accepts number parseable strings like "1"
40  tag_id: 1,
41
42  // Launch vehicle id
43  // Also accepts number parseable strings like "1"
44  vehicle_id: 1,
45
46  // US State
47  // ISO 3166-2 US State Code Abbreviation
48  state_abbr: "FL",
49
50  // Country of launch
51  // ISO 3166-1 Alpha 2 Country Code
52  country_code: "US",
53
54  // Search string
55  // Also accepts numbers like 2020
56  search: "Starlink",
57
58  // Unique launch slug as used on RocketLaunch.live
59  slug: "ses-20-ses-21",
60
61  // Limit amount of launches returned
62  // Must be between 1 and 25
63  // Also accepts number parseable strings like "10"
64  // Note: this param is safely ignored when using in conjuction with a Watcher (see below)
65  limit: 10,
66
67  // Sort order (by date) of results
68  // Accepts either "asc" or "desc"
69  // If left unfilled, API defaults to "asc"
70  direction: "asc",
71};

Locations

1const response = await client.locations(options);

Optional search parameters:

1const options = {
2  // Location numeric id
3  // Also accepts number parseable strings like "1"
4  id: 1,
5
6  // Location name
7  name: "Cape Canaveral",
8
9  // Location State (US)
10  // ISO 3166-2 US State Code Abbreviation
11  state_abbr: "FL",
12
13  // Location country
14  // ISO 3166 Alpha 2 Country Code
15  country_code: "US",
16};

Missions

1const response = await client.missions(options);

Optional search parameters:

1const options = {
2  // Mission numeric id
3  // Also accepts number parseable strings like "1"
4  id: 1,
5
6  // Mission name
7  name: "Juno",
8};

Pads

1const response = await client.pads(options);

Optional search parameters:

1const options = {
2  // Pad numeric id
3  // Also accepts number parseable strings like "1"
4  id: 1,
5
6  // Pad name
7  name: "SpaceX",
8
9  // Pad State (US)
10  // ISO 3166-2 US State Code Abbreviation
11  state_abbr: "FL",
12
13  // Pad country
14  // ISO 3166 Alpha 2 Country Code
15  country_code: "US",
16};

Tags

1const response = await client.tags(options);

Optional search parameters:

1const options = {
2  // Tag numeric id
3  // Also accepts number parseable strings like "1"
4  id: 1,
5
6  // Tag text
7  text: "Crewed",
8};

Vehicles

1const response = await client.vehicles(options);

Optional search parameters:

1const options = {
2  // Vehicle numeric id
3  // Also accepts number parseable strings like "1"
4  id: 1,
5
6  // Vehicle name
7  name: "Atlas V",
8};

Watcher

The rocket-launch-live-client has the ability to monitor the launches endpoint on a regular basis and return changes as they happen live.

1// Instantiate a new watcher
2// See below for options
3const watcher = client.watch(5, options);
4
5// Define event handlers
6watcher.on("new", (newLaunch) => {
7  // handle new launch
8});
9
10// Start monitoring
11watcher.start();
12
13// Stop monitoring
14watcher.stop();

Watcher Options

A new watcher takes up to two arguments:

1. Interval - (optional) (default: 5) - a duration, in minutes, between calls to the API. Adjust this based on the frequency you wish to stay up to date. To avoid needlessly querying the API, this client will now allow any option less than 1 minute.
2. Query Options - (optional) - The exact same query options that can be submitted to the launches endpoint. NOTE: the "limit" param is ignored on the watcher.

Query options cannot be altered on a running watcher. In order to change your search conditions, you'll need to stop the watcher and start a new one.

Watcher Methods and Properties

Start

Begin watching the launches endpoint using the interval and query options provided during watcher instantiation.

1watcher.start();

End

Stop watching the launches endpoint.

1watcher.stop();

On

Set an event handler for a Watcher event. Extends the Node Event Emitter on method. Takes an event name (see below) and a callback.

1watcher.on("ready", (launches) => {
2  // handle event
3});

Launches Data

Access the launches data cache. The data is stored in a JavaScript Map and has all the methods associated with Maps.

1watcher.launches; // Map of all launches in cache
2watcher.launches.size // Count of launches in cache
3watcher.launches.get(1) // Get launch with launch_id of 1
4watcher.launches.forEach((launch, launchId) => /* Do something to each launch */ )

Note: We recommend not altering the launches cache directly (such as by using Map's set or delete methods). The watcher will notice the discrepancy on the next API call and trigger appropriate new or change events to set it back. This may not be the behaviour you expect.

Watcher Events

Watcher events are triggered when the client recieves a response to a query to launches using the modified_since parameter. The client will compare the changes to a cached version of the launch and trigger the appropriate event.

If there are multiple changes on a single API call, the appropriate events will be triggered more than once, so have your callbacks handle a single event.

New

A new launch has been added! The Watcher will provide the new launch data as the first argument to your callback.

1watcher.on("new", (newLaunch) => {
2  // Handle the new addition here
3});

The newLaunch argument will be an RLLEntity.Launch object, the same shape as what is received from the launches endpoint (but not wrapped in the standard response).

Change

An existing launch has had information change. The Watcher will provide the old and new versions of the launch object to do your own comparisons.

1watcher.on("change", (oldLaunch, newLaunch) => {
2  // Handle changes here
3});

The oldLaunch and newLaunch will be the cached version and the new version of an RLLEntity.Launch object, the same shape as what is received from the launches endpoint (but not wrapped in the standard response).

Error

There was an error on an API call. The error will be passed as the first argument of the callback.

1watcher.on("error", (err) => {
2  // Handle error here
3});

The err object will have the following shape, and is accessible via TypeScript as RLLError:

1const err = {
2  error: "Error title";
3  statusCode: 404; // HTTP status code or null if no response
4  message: "Could not find this resource"; //  Custom error string from RLLC
5  server_response: { } // error passed through from server, can be null if no response
6}

Ready

The watcher has completed its initial API calls and built a cache of launches. The initial cache of launches is passed as the first argument. The client is now monitoring the API.

1watcher.on("ready", (launches) => {
2  // Handle ready here
3});

Initialization Errors

The watcher has experienced a problem setting up its initial cache and is has not started monitoring.

1watcher.on("init_error", (err) => {
2  // Handle error here
3});

The err object will have the following shape, and is accessible via TypeScript as RLLError:

1const err = {
2  error: "Error title";
3  statusCode: 404; // HTTP status code or null if no response
4  message: "Could not find this resource"; //  Custom error string from RLLC
5  server_response: { } // error passed through from server, can be null if no response
6}

Call

The watcher also emits a call event every time it makes a request, passing in the query parameters it used in the Node URLSearchParams format. Use this to monitor or diagnose how often the API is being queried.

1watcher.on("call", (params) => {
2  // Handle call here
3});