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;

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.