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 Started
  2. Looking up States
  3. Looking up Counties
  4. Looking up a Record
  5. Searching Records
  6. Code Samples
  7. API Status

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…