 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 two methods currently available: search and download.
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.
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 three criteria being used
to search for all Estes 18mm motors that have data files.
<search-request>
<manufacturer>Estes</manufacturer>
<diameter>18</diameter>
<has-data-files>true</has-data-files>
</search-request>
Hopefully, all this looks familiar to you.
If not, stop and familiarize yourself with XML before proceeding.
There is a very nice XML tutorial on the
W3 Schools site.
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 56 Animal Motor Works motors and 12 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 returned.
Note that 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
(up to 50 at a time).
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.
Example Program
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:
- Format and send the search request,
- Extract the resulting motor IDs from the search response,
- Format and send the download request,
- 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:
- Download ThrustCurveAPI.java to a local directory
- Compile it: javac ThrustCurveAPI.java
- Try it out: java ThrustCurveAPI -name L600
- 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).
In particular, there isn't a built-in pure-Java method of decoding Base64 so
that piece may be useful to you.
|
