README

Federal files that name a person in the National Archives Catalog of the United States (NARA), through its Catalog API v2, for omnisense/omnistate.

A catalogue of federal archives, not civil registration. Births, marriages and deaths in the United States are kept by the states and counties; the Catalog holds none of them as such. What it answers to a name is the description of federal files that mention it - pension application files, compiled military service records, draft registration cards, indexes to naturalization papers, Indian census cards, homestead certificates - with the series and record group they belong to, the reference room that holds them, and, for many, links to their scanned pages at NARA. Every record is of the kind OTHER.

$registry = new Nara($httpClient, $apiKey);
$files = $registry->search(new CivilQuery(familyName: 'Darwin', givenName: 'John', dated: Period::years(1775, 1900)));
$files[0]->title;      // "Revolutionary War Pension and Bounty Land Warrant Application File S. 21155, John Darwin, S.C. Va."
$files[0]->archive;    // National Archives at Washington, DC - Textual Reference, RG 15, M804, NAID 54373887
$files[0]->url;        // https://catalog.archives.gov/id/54373887
$files[0]->images;     // the scanned pages, at catalog.archives.gov

No framework needed: the package requires omnisense/omnistate and symfony/http-client. $httpClient is the HTTP client to call with - the application's, HttpClient::create() in plain PHP, a MockHttpClient in a test.

Keep answers in a cache: omnisense/omnistate does (Omnistate's cache, a day by default), and that is what keeps a search screen within the month's 10,000 calls.

Responsibility

This package is an independent, unofficial client: it is not affiliated with, endorsed by or sponsored by the U.S. National Archives and Records Administration. It reaches their service on behalf of whoever runs it, and it does not redistribute their data beyond the short excerpts recorded as test fixtures. Its MIT licence covers this package's code only and grants no right to the service or to its data.

Whoever installs and runs this package is responsible for complying with the National Archives Catalog API's terms (its terms of use), for obtaining whatever they require (an account, a key, a licence or subscription, an attribution or a citation, a rate limit to respect), and for any use made of what it returns. The authors publish it free of charge, make no commercial use of it, and accept no liability for how it is used (see LICENSE).

Documentation: docs/. License: MIT.