README

A PHP client for the National Archives Catalog API v2.

Installation

composer require survos/nara-php-api

This library requires Symfony HTTP Client (included as a dependency).

Quick Start

use Survos\Nara\ClientFactory;

$client = ClientFactory::create($yourApiKey);

// Search records (raw array response)
$results = $client->search(['q' => 'constitution']);
echo $results['body']['hits']['total']['value'];

// Search with typed DTOs
$results = $client->searchWithDtos(['q' => 'constitution']);
foreach ($results as $result) {
    echo $result->record->title;
    echo $result->record->naId;
}

// Search transcriptions
$transcriptions = $client->transcriptionsSearchWithDtos(['q' => 'constitution']);
foreach ($transcriptions as $t) {
    echo $t->contribution;
}

// Get single record by NA ID
$record = $client->getRecordByNaId(1667751);
echo $record->title;

Contributing data (write)

The Catalog API can also write contributions — transcriptions, tags, and comments — back to the National Archives. This is how you give OCR or human-keyed text a permanent home in the national record.

use Survos\Nara\ClientFactory;

// Writes need your API key *and* your Catalog user UUID (the contribution
// is attributed to that account). Set it once on the client...
$client = ClientFactory::create($yourApiKey, userId: $yourCatalogUuid);

// Submit the full text of a digital object as a transcription.
// Re-submitting overwrites the record's transcription (NARA keeps history).
$result = $client->submitTranscription(naId: 12345, transcription: $ocrText);

if ($result->success) {
    echo "Saved as contribution {$result->contributionId}";
} else {
    // 401/422 etc. are returned (not thrown) so a bulk loop can log & continue.
    echo "Failed (HTTP {$result->statusCode}): {$result->message}";
}

// Tags and comments work the same way:
$client->submitTag(521451, 'president');
$client->submitComment(521451, 'This photo also appears in series ...');

// Or pass the user UUID per call instead of on the client:
$client->submitTranscription(12345, $ocrText, userId: $someOtherUuid);

These map to POST /api/v2/{transcriptions,tags,comments}/ with a JSON body of { <text field>, targetNaId, userId }.

Enabling write access

Write access is not enabled on a standard read key. Email Catalog_API@nara.gov with your email and Catalog username to have contributions enabled for your key. You also need your Catalog user UUID — find it in the userId field of any of your existing contributions (e.g. GET /api/v2/contributions/search).

CLI: bin/contribute.php

A safe demo command — dry-run by default, it only writes when you pass --force:

export NARA_API_KEY="your-key"
export NARA_USER_ID="your-catalog-uuid"

# Preview exactly what would be sent (no write):
php bin/contribute.php transcription 12345 --text "Dear Sir, ..."

# Read the text from a file:
php bin/contribute.php transcription 12345 --text-file page1.txt

# Pipe OCR output straight in, then actually submit:
mistral-ocr page1.png | php bin/contribute.php transcription 12345 --force

API Key

To get an API key, email Catalog_API@nara.gov.

Demo

A CLI demo is included:

# Using environment variable
export NARA_API_KEY="your-key"
php bin/search.php search "constitution"

# Using --api-key option
php bin/search.php search "constitution" --api-key=your-key
php bin/search.php search "presidents" --limit=5

# Lookup by NA ID
php bin/search.php search 1667751

# Verbose output
php bin/search.php search "constitution" -vvv --limit=1

Bulk Data

For large-scale data access, NARA provides bulk downloads on AWS S3:

# Download full descriptions (87 GB)
aws s3 cp s3://nara-national-archives-catalog/zip/nac_export_descriptions_2025-04-08.zip ./ --no-sign-request

# Sync specific record group
aws s3 sync s3://nara-national-archives-catalog/descriptions/record-groups/rg_011/ ./rg011/ --no-sign-request

See NARA Developer Docs for more.

License

MIT License - see LICENSE file.