ThrustCurve API

This site provides a UI for searching for motors and downloading data right within any web browser. However, for those intrepid souls who would like to integerate the data provided by this site into programs (such as flight simulators), an API is provided.
Normal users of the site can just ignore this page.

The API described on this page provides basic database access through REST endpoints. Inputs can be specified as XML, JSON or form data and results can be returned as XML or JSON. The v1 API, described on this page, is a superset of the XML-only API supported by the v2 site. The "compatible endpoints" listed are those that were supported by the v2 site.

There are six actions supported:

Each action supports multiple endpoints:

  • JSON: request is query string (GET) or JSON object (POST), response is a JSON object
  • XML: request is query string (GET) or XML element (POST), response is an XML element
  • compatible: request (POST) and response are XML elements (deprecated)

The compatible endpoints are a legacy of the previous version of this site and have not changed (nor will they change in future). The XML endpoint is close to the compatible endpoint, but has some changes (the 2020 XML schema versions include those changes). The JSON and XML endpoints are versioned and new versions may be introduced over time.

While useful for web mashups, the API was designed to be used by rocket simulator programs so it does not require being called from a browser nor does it require any headers to be sent.

For those updating their code from the compatible (/servlets) to the newer (/api/v1) endpoints, the main difference is that IDs are not integers. In the newer APIs they are 24-digit hexadecimal numbers (such as "5f81c94736f9725a10f26a56"), but if your code treats the IDs as strings there is no real difference. Note that there are often more fields in the newer responses.

Finally, all measurements in this API use SI (MKS) units, except for motor mount tubes which are in millimeters. Note that while the web site and mobile app offer a choice of units in user preferences, internally they operate in SI for simplicity.

There is a OpenAPI (Swagger) spec for the JSON API and you can use Swagger Inspector to explore the API with it. You can Browse the hosted documentation or point Swagger Insector (or similar OpenAPI tool) at https://www.thrustcurve.org/api/v1/swagger.json .

Each API is described in its own section below. The JSON and XML endpoints support both GET and POST and the compatible endpoints support only POST (and only XML).

For an example of using the API, see the API demo page.

Metadata

JSON/api/v1/metadata.json
XML/api/v1/metadata.xml
compatible/servlets/metadata

The metadata API doesn't return stats or data on individual motors, but instead is used to find out what actual criteria exist for doing a search.

This is useful for building interactive programs that want to populate a set of combo boxes with valid search criteria, without hard-coding the actual values into the program. The simplest case is to return metadata encompasing all motors in the database using no input at all: /api/v1/metadata.json (or metadata.xml).

However, its usually desirable to get metadata only for the motors that the user of the API is actually interested in. For example, if you don't care about motors that are out of production, restricting the metadata to available motors makes more sense: /api/v1/metadata.json?availability=available. This endpoint accepts the same query as the search endpoint below.

Search

JSON/api/v1/search.json
XML/api/v1/search.xml
compatible/servlets/search

The search API is where it starts to get more interesting. This is the first API that requires inputs and returns data on specific motors in the the database. This API could be used to drive you own search front-end.

Search is useful for finding motors that match one or more criteria. You can specify a wide range of filters and retrieve all the data on the motors that match. Among other data is the unique ID of the motor which can be used to download data files.

Download

JSON/api/v1/download.json
XML/api/v1/download.xml
compatible/servlets/download

The download API is used to pull data files for motors you've previously found via search. The request specifies one or more motors and may also specify criteria for the simulator files.

Download is useful for retrieving the simulator data files uploaded to ThrustCurve.org. Once you have one or more motors found via search (above), you can use download to get their data files. You can specify a few criteria for the data files as well, such as the format.

There is also a feature to access the parsed data points in a standard format if you want to consume the data directly. In the request, specify data=samples to get the parsed data points instead of the file.

Get Rockets

JSON/api/v1/getrockets.json
XML/api/v1/getrockets.xml
compatible/servlets/getrockets

The getrockets API is used to pull saved rockets from your account in ThrustCurve.org. The request specifies the email address and password in the POST body, or using browser authentication for the GET method. Note that if a password is not specified, you can download the public rockets for any user whose email address you know.

This API is used by the mobile app to load your saved rockets into your device, but could potentially be useful to download this data for other uses.

Save Rockets

JSON/api/v1/saverockets.json
XML/api/v1/saverockets.xml

The saverockets API is used to save rocket definitions into your account in ThrustCurve.org. The request specifies the email address and password in the POST body, along with a list of rockets to save.

This API is used by the mobile app to save rockets entered into your device, but could potentially be useful to save rocket definitions created in other programs.

Motor Guide

JSON/api/v1/motorguide.json
XML/api/v1/motorguide.xml
compatible/servlets/motorguide

The motorguide API is used to find motors that will work for a rocket. The request specifies key information on the rocket (same the info entered into the motor guide page).

This API is used to power the mobile app feature of the same name. It can also be used to find working motors by external sites or programs that have rocket design information.