Developers
We believe in the openness of data, which is why we’re pleased to present our REST API.
The REST API allows developers to access the data and search methods available through this project. To learn more about REST, please click here. The following documentation explains how to use the API within your application. Language-specific code is currently being compiled, and will be available to download here once complete. Please keep checking our Blog for releases and API information.
Table of Contents
Use the table of contents below to quickly navigate to the relevant documentation:
1. Getting StartedTable of Contents
The RESTful API that is provided by WWII US Army Enlistment Records is, for now, read-only. There is currently no means by which
data can be added to our collections through the API. Such functionality might be introduced in a later version of the API, but
this is not currently a road-mapped addition.
As a result, all HTTP requests to the API should be made as GET
requests, passing through additional parameters
as required.
Use of the API does not require an API key, and is not limited in any way. Developers can make as many calls to the API as required, and there is no throttling in place.
The API provides 4 endpoints, which can be accessed via requests made to: http://wwii-enlistment.com/api/
, as follows:
states/
counties/
record/
search/
If you wanted to access all States, for example, you can send a GET
HTTP request to the endpoint:
http://wwii-enlistment.com/api/states/
Further information about each endpoint is explained in this documentation, allowing with supported and default parameters for each. All endpoints will return data in JSON format.
2. Looking up StatesTable of Contents
Description:
The states
endpoint will return all of the States used within the data. If the code
parameter is specified, the State with a matching code will be reutrned.
Overview:
Endpoint: | states |
URL: | http://wwii-enlistment.com/api/states/ |
HTTP verb: | GET |
Parameters:
Parameter | Type | Required? | Default | Description |
---|---|---|---|---|
code | Integer | false | NULL |
Specifies the State code to be used for the lookup. Returns exact matches only. |
Returned data sample:
Response:
[ {"code": "41", "name": "Alabama"}, {"code": "D1", "name": "Alabama"}, {"code": "M1", "name": "Alabama"}, {"code": "R0", "name": "Alaska"}, {"code": "02", "name": "Alaska"}, {"code": "N9", "name": "Albania"}, {"code": "O5", "name": "Andorra or Portugal"}, ... {"code": "J9", "name": "Argentina"}, {"code": "R8", "name": "Arizona"}, {"code": "I8", "name": "Arizona"} ]
3. Looking up CountiesTable of Contents
Description:
The counties
endpoint will return a list of all counties within a given state. If the code
parameter is specified, the County matching the provided code will be returned.
Overview:
Endpoint: | counties |
URL: | http://wwii-enlistment.com/api/counties/ |
HTTP verb: | GET |
Parameters:
Parameter | Type | Required? | Default | Description |
---|---|---|---|---|
code | Integer | false * | NULL |
Specifies the County code to be used for the lookup. Returns exact matches only. |
state | Integer | false * | NULL |
Specifies the State code to be used for the lookup. Returns all Counties within the specified State. |
* Please note: While none of the parameters is explicitly required, at least one must be
provided as part of the request. Failure to provide one of the search parameters will result in a
400 - Bad Request
status.
Returned data sample:
Request:
[ "state" : 41 ]
Response:
[ { "code": "1", "name": "Autauga", "stateCode": "41", "state":"ALABAMA" }, { "code": "3", "name": "Baldwin", "stateCode": "41", "state": "ALABAMA" }, { "code": "5", "name": "Barbour", "stateCode": "41", "state": "ALABAMA" }, { "code": "7", "name": "Bibb", "stateCode": "41", "state": "ALABAMA" }, ... ]
4. Looking up a RecordTable of Contents
Description:
The record
endpoint will return all available data belonging to an individual Record. The Army
Serial Number of the personnel should be passed by the asn
parameter.
Overview:
Endpoint: | record |
URL: | http://wwii-enlistment.com/api/record/ |
HTTP verb: | GET |
Parameters:
Parameter | Type | Required? | Default | Description |
---|---|---|---|---|
asn | String | true | NULL | Specifies the Army Serial Number (ASN) to be used for the search. |
Returned data sample:
Request:
[ "asn": "38098123" ]
Response:
{ "asn": "38098123", "laundryNumber": "S-8123", "forename": "William", "middleName": "A", "surname": "Simms", "verboseName": "William A. Simms", "enlistmentDate": "-878004000", "enlistmentPlace": "Cp Wolters Texas", "residence": "Dallas, Texas", "armyComponent": "Selectees (Enlisted Men)", "branch": "Quartermaster Corps", "source": "Civil Life", "nativity": "Texas", "race": "White, citizen", "birthYear": "1907", "education": "1 year of high school", "occupation": "Clerks", "maritalStatus": "Married", "grades": [ "Private" ], "units": [ ], "images": [ ], "searcherName": "Simms, William A." }
Please note: The enlistmentDate
property is a Unix timestamp, representing the
number of seconds before the Epoch, stored as a negative integer (in seconds).
5. Searching RecordsTable of Contents
Description:
Perform a search of records in the WWII US Army Enlistment Records database. One or more search parameters
can be passed with the request.
Will return an array of Record objects, sorted by the specified sort method.
Overview:
Endpoint: | search |
URL: | http://wwii-enlistment.com/api/search/ |
HTTP verb: | GET |
Parameters:
Parameter | Type | Required? | Default | Description |
---|---|---|---|---|
asn | String | false * | NULL | Specifies the Army Serial Number (ASN) to be used for the search. |
forename | String | false * | NULL |
Specifies the forename to be used for the search. It is not recommended to use this as the only search parameter. |
surname | String | false * | NULL |
Specifies the surname to be used for the search. Returns exact matches only; wildcards are not supported. |
laundryNumber | String | false * | NULL |
Specifies the Laundry Number to be used for the search. Accepted examples: "W-5394" or "W5394". |
residenceState | String | false * | NULL |
Specifies the code relating to the residence state to be used for the search. Accepted examples: "41" (Alabama) or "46" (North Carolina) Codes can be found using the states endpoint.
|
residenceCounty | String | false * | NULL |
Specifies the code relating to the residence county to be used for the search. Accepted examples: "1" (Autauga) or "7" (Bibb) Codes can be found using the counties endpoint.Must be used in conjunction with residenceState parameter.
|
birthYear | Integer | false * | NULL |
Specifies the year of birth to be used for the search. Accepted examples: "1860" or "1920" Must be a 4-digit integer. |
sortBy | String | false | (string) "surname" |
Specifies the field to be used for sorting the data. Accepted values: "asn", "surname", "enlistmentDate" |
sortDir | String | false | (string) "ASC" |
Specifies the sorting direction Accepted values: "ASC" (ascending) or "DESC" (descending) |
page | Integer | false | (int) 1 |
Specifies the page number of results to be returned. Recommended to be used in conjunction with limit .
|
limit | Integer | false | (int) 30 |
Specifies the number of results to return per page. Recommended to be used in conjunction with page .
|
* Please note: While none of the search parameters is explicitly required, at least one must be
provided as part of the request. Failure to provide at least one of the search parameters will result in a
400 - Bad Request
status.
Returned data sample:
Request:
Search for all personnel with a surname of "Gates", sorting ascendingly by the enlistment date (returns the first two results).
[ "surname": "Gates", "sortBy": "enlistmentDate", "sortDir": "DESC", "page": 1, "limit": 2 ]
Response:
{ "results": [ { "asn": "06394986", "laundryNumber": "G-4986", "forename": "Valrus", "middleName": "", "surname": "Gates", "verboseName": "Valrus Gates", "enlistmentDate": "-958784400", "enlistmentPlace": "Raleigh North Carolina", "residence": "Unknown", "armyComponent": "Regular Army (including Officers, Nurses, Warrant Officers, and Enlisted Men)", "branch": null, "source": null, "nativity": "", "race": "White, not yet a citizen", "birthYear": "1844", "education": "1 year of college", "occupation": "Skilled occupations in manufacture of miscellaneous electrical equipment", "maritalStatus": "Single, without dependents", "grades": [ "Technician 3d Grade" ], "units": [ ], "images": [ ], "searcherName": "Gates, Valrus " }, ... ], "sortBy": "enlistmentDate", "sortDir": "DESC", "numResults": 1957 }
Please note: The enlistmentDate
property is a Unix timestamp, representing the
number of seconds before the Epoch, stored as a negative integer (in seconds).
6. Code SamplesTable of Contents
The RESTful API returns data in JSON format, which means that it can be easily used across platforms and programming languages. The sample code provided here is for demonstration purposes only, and use of the API is certainly not limited to the languages presented here.
PHP sample using cURL:
// Set up our cURL request: $c = curl_init(); curl_setopt($c, CURLOPT_RETURNTRANSFER, 1); curl_setopt($c, CURLOPT_HTTPHEADER, array('Accept: application/json', 'Content-Type: application/json')); curl_setopt($c, CURLOPT_URL, 'http://wwii-enlistment.com/api/record/'); curl_setopt($c, CURLOPT_POSTFIELDS, '{asn:"06394986"}'); $content = curl_exec($c); curl_close($c); // $content needs to be decoded to provide us with JSON: $json = json_decode($content); // Print it out, or use $json as you need: print_r($json);
jQuery sample using $.getJSON
:
// Set our variables: var endpointUrl = 'http://wwii-enlistment.com/api/record/', data = { 'asn': '06394986' }; // Perform the request, using always() to handle the return: $.getJSON(endpointUrl, requestData).always(function(data, status, request) { // The request status is OK: if(request.status == 200) { // data now contains our JSON: console.log(data); } else { // The API returned an status code other than 200 (OK). // Hanlde gracefully in your app. } });
7. API StatusTable of Contents
Endpoint | Latency | Status |
---|---|---|
states |
Waiting… | Waiting… |
counties |
Waiting… | Waiting… |
record |
Waiting… | Waiting… |
search |
Waiting… | Waiting… |