Search for Motors Automatically Find Motors Login or Edit Settings Data File Outbox ThrustCurve.org home ThrustCurve.org

Search & Download XML 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 XML API is provided. This page assumes a familiarity with XML and network programming; normal users of the site can just ignore this page.

OK, so you want to query the ThrustCurve.org database from your program; what do you need to get started? At a minimum, you need to understand XML and basic network programming. You will need to be able to form a valid XML document for the query, send it over the network to this site using the HTTP protocol, receive the response and decode the resulting XML document.

There are three methods currently available: search, download and metadata. Search is a programmatic version of the Motor Search page; you specify various criteria and matching motors are returned. Download is a programmatic version of the Outbox page; you specify one or more motors and the data for them is returned. Metadata is used to determine what actual criteria are possible when forming searches.

Search API

The XML request message is designed to be as easy to specify as possible. The top-level search-request element contains one or more criteria, each a simple child element, in any order. For the full specification, see the XML schemas for the request and response message documents.

Here's a very simple example, showing just a single search criterion:

<search-request>
  <common-name>L600</common-name>
</search-request>

Here's a slightly more complex example, showing four criteria being used to search for all Estes 18mm motors that have data files and are in production.

<search-request>
  <manufacturer>Estes</manufacturer>
  <diameter>18</diameter>
  <has-data-files>true</has-data-files>
  <availability>available</availability>
</search-request>

Hopefully, all this looks familiar to you. If not, stop and familiarize yourself with XML before proceeding. There are tutorials on the web as well as several entire books on the subject, although the syntax is mostly self-explanatory.

Roughly the same set of criteria can be specified in the request as can be selected in Advanced Search on the Motor Search page. You can view the request XML schema in your browser or download it as a file and view it with your XML development tool of choice. The URL for the search API is: http://www.thrustcurve.org/servlets/search.

The response returns the list of criteria specified, with an indication of whether or not there was an error and how many motors that criterion matched on its own. This is helpful when debugging why no motors matched, since all criteria are applied (an "and" operation). For example if the criteria "manufacturer: AMW" and "impulse-class: A" are specified, no motors will be returned. (Even though there are numerous Animal Motor Works motors and a dozen or so A motors, sadly there are no AMW A motors.)

Of course, the most interesting part of the response is the list of results. For each result, there is the motor-id (which is used for the download API) as well as a bunch of info on the motor which can be used for display and/or further selection. You can view the response XML schema for the full set of data fields available.

You can control which fields are returned for each motor using the data-fields element in the request. If unspecified, a standard subset is returned, but you can also specify which ones you want. To specify all the fields, or to get the list of all fields names, use an asterisk:

<search-request>
  <common-name>K500</common-name>
  <data-fields>*</data-fields>
</search-request>

To specify the fields you want, use a comma-separated list of element names. Note the all the data fields are optional in the respose (except motor-id) and those fields for which the value is unknown will not appear in the output.

The number of matches for all criteria in combination is returned as a final matches element within the criteria element. This is useful in the case where fewer results are returned than match the criteria. Normally, only the first 20 matches are returned. The max-results element may be specified in the request to increase this number.

Download API

The download API is very similar and equally simple. The primary thing to note is that either one or a list of motor ids are specified, along with some optional criteria on the type of data desired. See the request XML schema for details.

Following our first example above (searching for all L600 motors), let's say we wanted to download all RASP data for the Ellis L600. (The motor id is 375, which we got from using the search API.) Here is a sample request for the download API:

<download-request>
  <motor-id>375</motor-id>
  <format>RASP</format>
</download-request>

Note that you can specify multiple motors in one request. In that case use the motor-ids element with multiple child id elements. It is also valid to use the motor-ids element with just a single motor if that simplifies your code. The only restriction is that at least one motor id must be specified.

There may be zero or more data files available for each motor requested so you must be prepared to match up the response motor-id values to the requested motors. See the response XML schema for details. The URL for the download API is: http://www.thrustcurve.org/servlets/download.

A final detail is worth metioning. The actual motor data is returned as a Base64 encoded string. This is a commonly used method of encoding binary data for transmission through text-based mechanisms. See the Wikipedia article for more information.

Like the search API, the download API also includes an information URL for each data file. In addition, it includes a download URL (data-url) which can be used as an alternative method for getting the actual simulation data.

Metadata API

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. See the request XML schema for details.

This is useful for building interactive programs that want to populate a set of combo boxes with all the 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 an empty request element:

<metadata-request/>

Each of the five response top-level elements (manufacturers, cert-orgs, types, diameters, impulse-classes) will always be present, but the number of child elements in each list will vary. See the response XML schema for details. The URL for the download API is: http://www.thrustcurve.org/servlets/metadata.

Note that it's also possible to restrict the motors considered using search criteria in the request (see the Search API above). In that case, metadata relevent to only the motors that match those search criteria will be returned. For example:

<metadata-request>
  <impulse-class>C</impulse-class>
  <availability>regular</availability>
</metadata-request>

Will return the same five lists, but with fewer individual values in each. I.e., there are only a few manufacturers that make C motors still in regular production.

Example Programs

Let's put it all together with an example program to get you started. I have written a simple driver that allows you to query motors in various ways and automatically downloads the matching data. This provides an example of using both APIs as well as showing the XML data being sent and received. Download the source code at ThrustCurveAPI.java.

For simplicitly, the example is all in a single Java source file. Most of the main function is boilerplate, but the sections at the bottom show the key steps:

  1. Format and send the search request,
  2. Extract the resulting motor IDs from the search response,
  3. Format and send the download request,
  4. Extract the resulting sim data from the download response.

Formatting the search request is straight-forward; the main function collects command-line arguments that allow specification of the various search criteria, which are then packaged as a XML document (see search-request.xsd for details).

To run the example, you must have the Java 1.5 SDK (J2SE) or later. You can download the current Java compiler and tools from the Sun Java site. (Note that the JRE, which is pre-installed on many systems, is sufficient to run Java programs, but not to compile Java source code.)

If you are not programming in Java, you may also just look at the example code for reference. If you do want to run the example, here's how:

  1. Download ThrustCurveAPI.java to a local directory
  2. Compile it: javac ThrustCurveAPI.java
  3. Try it out: java ThrustCurveAPI -name L600
  4. Examine results:
    • search-request.xml request document sent to search API
    • search-response.xml response document received from search API
    • download-request.xml request document sent to download API
    • download-response.xml response document received from download API
    • *.data extracted data files

Note that there are many command line options to the program; run it with no arguments for a complete usage list. In particular, all the criteria for the search API can be specified on the command line.

Hopefully the Java source code is clear enough to allow you to program to the APIs in your language of choice. If someone translates this into in another language, please send it to me and I will post it as an additional example.

You are free to use any part of this example in your own code (with proper attribution of course).

I've also written a one-page app that demonstrates accessing these APIs from JavaScript. See a JavaScript mash-up approach.

---
ThrustCurve.org home