Search Technologies Assessment - National Archives



National Archives and Records AdministrationNational Archives Catalog (The Catalog)NARA Catalog Internal API Design– Catalog Perspective –Status-FinalVersion 1.1July 6, 2015righttopNational Archives & Records AdministrationNARA Catalog Internal API DesignVersion 1.1July 6, 2015Contents TOC \o "2-3" \h \z \t "Heading 1,1" 1Overview PAGEREF _Toc423958964 \h 31.1Other Relevant Documents PAGEREF _Toc423958965 \h 31.2NARA Catalog Content PAGEREF _Toc423958966 \h 31.3API Philosophy PAGEREF _Toc423958967 \h 51.4General API Structure PAGEREF _Toc423958968 \h 61.4.1The NAID PAGEREF _Toc423958969 \h 61.4.2The OPA-ID PAGEREF _Toc423958970 \h 61.4.3Other Identifiers PAGEREF _Toc423958971 \h 71.4.4Examples PAGEREF _Toc423958972 \h 81.5API Responses PAGEREF _Toc423958973 \h 81.5.1API Response Formats PAGEREF _Toc423958974 \h 81.5.2General Response Structure PAGEREF _Toc423958975 \h 91.6Authentication PAGEREF _Toc423958976 \h 111.6.1Login through Catalog PAGEREF _Toc423958977 \h 111.6.2Login with Third Party Authentication [LOW PRIORITY – RELEASE 2] PAGEREF _Toc423958978 \h 121.6.3Login Error Codes PAGEREF _Toc423958979 \h 131.6.4Acquiring Catalog Credentials PAGEREF _Toc423958980 \h 131.6.5Using Catalog Credentials PAGEREF _Toc423958981 \h 131.7Registration PAGEREF _Toc423958982 \h 131.8Configuration PAGEREF _Toc423958983 \h 131.9Storage PAGEREF _Toc423958984 \h 142Access API PAGEREF _Toc423958985 \h 162.1The URL Path Map PAGEREF _Toc423958986 \h 162.1.1Why use the Access API? PAGEREF _Toc423958987 \h 172.1.2Other paths in PAGEREF _Toc423958988 \h 172.2Top-Level Path – /iapi/v1 PAGEREF _Toc423958989 \h 182.3Holdings – /iapi/v1/id PAGEREF _Toc423958990 \h 182.3.1The NAID – /iapi/v1/id/<NAID> PAGEREF _Toc423958991 \h 182.4Authority Records – /iapi/v1/id PAGEREF _Toc423958992 \h 342.4.1People – /iapi/v1/id/<person-id> PAGEREF _Toc423958993 \h 342.4.2Organizations – /iapi/v1/id/<org-id> PAGEREF _Toc423958994 \h 362.5User Information – /iapi/v1/accounts PAGEREF _Toc423958995 \h 393Search API PAGEREF _Toc423958996 \h 403.1Overview PAGEREF _Toc423958997 \h 413.1.1Search Results Entries PAGEREF _Toc423958998 \h 413.1.2Annotations PAGEREF _Toc423958999 \h 423.1.3Search Functions PAGEREF _Toc423959000 \h 443.2Search API Parameters PAGEREF _Toc423959001 \h 453.3Query Expressions PAGEREF _Toc423959002 \h 533.3.1Keyword Fields PAGEREF _Toc423959003 \h 533.3.2String Fields PAGEREF _Toc423959004 \h 543.3.3Date and Date-Time Fields PAGEREF _Toc423959005 \h 553.3.4Integer Fields PAGEREF _Toc423959006 \h 563.3.5XML Fields PAGEREF _Toc423959007 \h 563.4Fields PAGEREF _Toc423959008 \h 583.4.1Identifiers PAGEREF _Toc423959009 \h 593.4.2Types PAGEREF _Toc423959010 \h 603.4.3Display Fields PAGEREF _Toc423959011 \h 633.4.4More Facet Fields PAGEREF _Toc423959012 \h 643.4.5Archival Hierarchy Fields PAGEREF _Toc423959013 \h 653.4.6Digital Object Information PAGEREF _Toc423959014 \h 653.4.7Annotations PAGEREF _Toc423959015 \h 663.4.8XML Fields PAGEREF _Toc423959016 \h 673.4.9Authority Information PAGEREF _Toc423959017 \h 683.4.10Dates and Times PAGEREF _Toc423959018 \h 693.5Search Results Output PAGEREF _Toc423959019 \h 713.5.1Header Information PAGEREF _Toc423959020 \h 723.5.2Search Results PAGEREF _Toc423959021 \h 743.5.3Web Page Results PAGEREF _Toc423959022 \h 823.5.4Pdf Files Results PAGEREF _Toc423959023 \h 843.5.5Facet Values PAGEREF _Toc423959024 \h 853.5.6Highlights PAGEREF _Toc423959025 \h 873.5.7Thesaurus Expansions PAGEREF _Toc423959026 \h 883.5.8Complete Example PAGEREF _Toc423959027 \h 913.6Exports PAGEREF _Toc423959028 \h 1003.6.1Specifying What Results to Export PAGEREF _Toc423959029 \h 1003.6.2Parameters PAGEREF _Toc423959030 \h 1003.6.3Examples PAGEREF _Toc423959031 \h 1033.6.4Response (standard export) PAGEREF _Toc423959032 \h 1043.6.5Bulk Exports PAGEREF _Toc423959033 \h 1053.7Search based Content Detail PAGEREF _Toc423959034 \h 1063.7.1Content Detail result PAGEREF _Toc423959035 \h 1063.7.2Jump to Page functionality PAGEREF _Toc423959036 \h 1084Annotations API PAGEREF _Toc423959037 \h 1104.1The Basics PAGEREF _Toc423959038 \h 1104.1.1Annotations are attached to content PAGEREF _Toc423959039 \h 1104.1.2Modifying annotations requires login PAGEREF _Toc423959040 \h 1114.1.3Editing annotations PAGEREF _Toc423959041 \h 1114.1.4Contributed Annotations by user PAGEREF _Toc423959042 \h 1114.1.5Annotation parameter validation PAGEREF _Toc423959043 \h 1114.2Annotations Summary Information PAGEREF _Toc423959044 \h 1124.3Comments API PAGEREF _Toc423959045 \h 1154.3.1Fetching Comments and Replies PAGEREF _Toc423959046 \h 1154.3.2Modifying Comments and Replies PAGEREF _Toc423959047 \h 1194.3.3Bulk Import of Comments PAGEREF _Toc423959048 \h 1224.4Tagging API PAGEREF _Toc423959049 \h 1234.4.1Fetching Tags PAGEREF _Toc423959050 \h 1234.4.2Modifying Tags PAGEREF _Toc423959051 \h 1254.4.3Bulk Import of Tags PAGEREF _Toc423959052 \h 1274.5Transcription API PAGEREF _Toc423959053 \h 1284.5.1Fetching a Transcription PAGEREF _Toc423959054 \h 1284.5.2Modifying Transcriptions PAGEREF _Toc423959055 \h 1304.5.3Bulk Import of Transcriptions PAGEREF _Toc423959056 \h 1334.6Translation API PAGEREF _Toc423959057 \h 1344.6.1Fetching a List of all Translations PAGEREF _Toc423959058 \h 1344.6.2Fetching a Translation PAGEREF _Toc423959059 \h 1374.6.3Modifying Translations PAGEREF _Toc423959060 \h 1394.6.4Bulk Import of Translations PAGEREF _Toc423959061 \h 1425User Contributions and Activities API PAGEREF _Toc423959062 \h 1445.1User Summary Information PAGEREF _Toc423959063 \h 1445.2User Contributions PAGEREF _Toc423959064 \h 1455.2.1Contributions Summary PAGEREF _Toc423959065 \h 1465.2.2Common Parameters for Contributions PAGEREF _Toc423959066 \h 1485.2.3User Contributed Comments PAGEREF _Toc423959067 \h 1495.2.4User Contributed Tags PAGEREF _Toc423959068 \h 1525.2.5User Contributed Transcriptions PAGEREF _Toc423959069 \h 1555.2.6User Contributed Translations PAGEREF _Toc423959070 \h 1565.3My Lists PAGEREF _Toc423959071 \h 1585.3.1Managing the List of Lists PAGEREF _Toc423959072 \h 1585.3.2Managing a Single List PAGEREF _Toc423959073 \h 1605.3.3Creating or Adding to a List using the Search API PAGEREF _Toc423959074 \h 1615.3.4Managing List Results PAGEREF _Toc423959075 \h 1625.4Bulk Exports PAGEREF _Toc423959076 \h 1695.4.1Fetching the List of Bulk Exports PAGEREF _Toc423959077 \h 1695.4.2Downloading a Bulk Export File PAGEREF _Toc423959078 \h 1715.4.3Deleting a Bulk Export PAGEREF _Toc423959079 \h 1715.5Notifications PAGEREF _Toc423959080 \h 1715.5.1Parameters PAGEREF _Toc423959081 \h 1725.5.2Response PAGEREF _Toc423959082 \h 1725.5.3Clearing Notifications PAGEREF _Toc423959083 \h 1745.5.4Error Codes PAGEREF _Toc423959084 \h 1745.6Account Information PAGEREF _Toc423959085 \h 1745.6.1Viewing Account Information PAGEREF _Toc423959086 \h 1755.6.2Modifying Account Information PAGEREF _Toc423959087 \h 1756URL mapping to support selected OPA pilot URLs PAGEREF _Toc423959088 \h 1786.1Mapping legacy URLs to Catalog URLs PAGEREF _Toc423959089 \h 1787Scheduled maintenance processes PAGEREF _Toc423959090 \h 1797.1Account maintenance processes PAGEREF _Toc423959091 \h 1798Appendices PAGEREF _Toc423959092 \h 1808.1Location IDs PAGEREF _Toc423959093 \h 1808.2Technical Metadata PAGEREF _Toc423959094 \h 1818.3Third-Party Authentication [LOW PRIORITY – RELEASE 2] PAGEREF _Toc423959095 \h 1818.4Languages PAGEREF _Toc423959096 \h 181Version ControlVersionDateReviewerSummary Description0.12013-12-20Elizabeth HobbsInitial Draft0.22014-01-12Elizabeth HobbsAdded information to introductory and annotations sections.0.32014-02-02Elizabeth HobbsFurther information for annotations and user contributions.0.42014-02-05Paul NelsonReview and adjustments overall. Work through sections 1-3 and 4.3.0.52014-02-10Elizabeth HobbsSection 5.0.62014-02-17Elizabeth HobbsRevisit section 4 with global updates and reformatting. Complete most of it.0.72014-02-18Paul NelsonAnother top-to bottom cleansing and polishing. Rework technical metadata section and file inventory. Add full NAID section. Rework some paths to map onto XML structures better.0.82014-02-19Paul NelsonReview and cleanup section 5.0.92014-02-21Paul NelsonReview and cleanup section 4.0.102014-02-22Paul NelsonReview and cleanup section 3. Complete search results section. Add nested objects. Add group=description. Cleanup other grouping types. Fields cleanup.0.112014-02-23Paul NelsonAdd exports, and lists to section 3. Add method to fetch all translations. Rework export formats and export options. Cleanup of section 3. Add transcriptions/translations to inventory XML. Allow multiple tag formats. Allow for multiple errors in OPA response.0.122014-02-25Madhu KoneniReview0.132014-02-25Paul NelsonImplement last-minute comments from NARA.0.142014-03-06Kristy MartinInternal review0.152014-03-09Paul NelsonFurther modifications based on customer comments received on 2/28 and 3/10.0.162014-03-15Paul NelsonRename this guide the “Internal API Design Document”0.172015-03-18Luis VargasAdded UI support items for Congressional Fields.0.182015-03-26Luis VargasRemoved UI support items for Congressional fields.1.02015-04-20Luis VargasAlejandro BaltodanoContent detail changes, S3 implementation, configuration refactors, URL mapping.Sections:1.81.93.74.1.561.12015-07-06Alejandro BaltodanoUpdate configuration sectionAdded API scheduler documentationSection 7Rebranding to NARA CatalogUpdated endpointsUpdated section 3.5.4OverviewThis document is the internal API design document to support the Catalog user interface.Specifically, this document will cover:Access API – Accessing and downloading content by URL from NARA CatalogSearch API – Searching for content using the search engine, returning brief results.Annotations API – Accessing, adding, updating, and deleting tags, transcriptions, discussions, and translations.User API – Anything which is user-related, such as information for the user’s home page, user lists, bulk downloads, and viewing user contributions.Other Relevant DocumentsOther documents relevant to this document:NARA Catalog User Interface DesignIdentifies all end-user functionality which must be supported by these APIs. OPA Architecture DesignExplains the data model for information in Catalog.NARA Catalog Archival Descriptions DMDIdentifies the metadata fields available for NARA archival descriptions and associated digital objects and what functions are possible for each field.NARA Catalog Authority Records DMDIdentifies metadata fields available for NARA authority records and what functions are possible for each field.NARA Catalog Web Sites DMDIdentifies metadata fields for results from , blogs, and all presidential library web sites, and what functions are possible for each field.NARA Catalog ContentContent in Catalog is a rich mixture of many types of information:Archival Descriptions – contain descriptive metadata about the holdings.Example metadata includes title, dates covered, creator, author, etc.Archival descriptions will describe both on-line content as well as physical materials which can only be viewed by visiting one of the Archive’s facilities.Digital Objects – are digital copies of the on-line holdings which can be downloaded and viewed through Catalog.Technical Documentation – is information (PDFs, usually) about the content, how it was collected, for what purpose, the formatting, etc.Authority Records – represent people, places, locations (i.e. geographic subjects), topics (i.e. topical subjects) and organizations.The primary purpose of authority records is to link archival descriptions to famous people, organizations, locations, topics, etc. in a uniform fashion.Currently, only people and organizations can be retrieved from Catalog.Contributions / Annotations – are for information added to NARA holdings by users of Catalog. This can include:Transcriptions – Transcribed text from scanned documents, audio recordings, or video recordings.Translations – Translated versions of the ments – Discussions about the holdings.Tags – User generated tags to aid in the search and categorization of the holdings.Web Pages – Catalog will crawl the web site and all of the presidential web sites. All web pages crawled by Catalog will be included in the Catalog search engine index.The information in Catalog falls into several different categories. The point of identifying these categories is to note that not all OPA information is appropriate for all API calls.Searchable Information: includes all things which are indexed into the Catalog search engine and which can be retrieved by searches. This includes:Archival DescriptionsAuthority RecordsDigital Objects (scanned images, videos, audio files, etc.)Web PagesThe content and fields of these items will be indexed when available.Annotatable Information: includes everything which can be annotated by a user.Annotations consist of tags, comments, translations, and transcriptions.Not everything can have the same annotations:Archival Descriptions – Tags and commentsAuthority Records – Tags and commentsDigital Objects (scanned images, videos, audio files, etc.) – Tags, comments, transcriptions, translationsWeb Pages – Web pages cannot be annotated via Catalog.Accessible Information: includes everything which can be accessed directly with a URL, including:Archival DescriptionsAuthority Records Digital ObjectsAlternative renditions of content, including:Thumbnails, tiled images (for now), XML representations of text content and content fieldsDownloadable packages, including:Database files, reformatted database files, and pre-packaged ZIP filesDissemination Information Packages (DIPs) – [not expected for OPA release 1] are official representations of archival packages exported from Catalog that are self-descriptive so they can be imported into other systems.Annotations – Tags, comments, replies, transcriptions, translationsAPI PhilosophyCatalog APIs are RESTful, and support the GET, POST, PUT, and DELETE methods:GET is recommended to access content with a simple URL (see section REF _Ref381118102 \r \h 2, the Access API) and for searches (see section REF _Ref379443499 \r \h 3)POST is used when creating new things (e.g. creating new annotations)PUT is used when updating something (e.g. saving annotations)DELETE is used when removing things (e.g. deleting annotations)The proper HTTP Request method to use for every function will be identified in the documentation.In general, the goal of each API transaction is to return all the information needed so a user interface application can create an appropriate page from the response. Additional clicks required to display something (i.e. click on a tab, click on a link to see a pop-up) will typically require a second transaction.When Using POSTIn the documentation below, this documentation will specify example URLs as follows:POST de Parkinson%22 aplicado a las instituciones podría sugerir que a medida...Note, however, when using POST, it is expected that all of the content after the “?” will be transmitted as request data (i.e. not in the URL itself, like it would be for a simple GET).General API StructureAPIs consist of a URL path, an optional action, and one or more parameters with values:URL Path – Identifies the scope of content which is affectedThis can be the item fetched or the scope of the content to be listed.Other parameters – [optional] Additional parameters may be needed to provide additional information, control how the API is executed, or specify how the results should be returned.The NAIDThe primary identifier for OPA will be the “National Archives ID” (NAID), which is used to access all content. NAID in this context refers only to the identifier for Archival Descriptions.All archival descriptions will have an NAID, and all content (digital objects, contributions, data files, etc.) will be grouped under the appropriate NAID.As an example, the “Letter from George McGovern to Harry S. Truman, 08/19/1972” has the NAID 7226539. This means that the descriptive metadata for this item can be retrieved using:GET OPA-IDThe OPA-ID uniquely identifies each and every entry in the search engine index. The format of the OPA-ID depends on the type of data:Archival descriptionsFormat: desc-{NARA ID}Example: desc-7226539People authority recordsFormat: person-{NARA ID}Example: person-8889Organization authority recordsFormat: org-{NARA ID}Example: org-15238Geographic subject authority recordsFormat: geo-{NARA ID}Example: geo-8889Topical Subject authority recordsFormat: top-{NARA ID}Example: top-15238Special Record Types authority recordsFormat: srt-{NARA ID}Example: srt-15238Digital ObjectsFormat: desc-{NARA ID}/{OBJECT-ID}Example: desc-7226539/32Web pagesFormat: {URL}Example: IdentifiersMost everything in NARA will also have an identifier, which will be used to fetch that item.Authority Record ID – There are two different types of authority records, “people” and “organizations”:Every authority record which represents a person will have a person IDEvery authority record which represents an organization will have an organization IDObject IDs – For on-line content, identifies individual digital objects within an NAID.Object IDs will be the stable ID from DAS or the ID from the SEIP [TBD – Requires discussion, object IDs not in ARC XML].Comment IDs – Every comment and reply will have an ID.Tag – The tag text will serve as the unique identifier for a tag.ExamplesFetch the Archival Description for NAID 7226539:GET Return the description in JSON:GET all description-level comments for 7226539:GET save a Spanish translation for the “263-a1-27-box-7-89-4-0002.jpg” object within the item with NAID 7226539:POST de Parkinson%22 aplicado a las instituciones podría sugerir que a medida...A simple search request with some parameters:GET API Responses API Response FormatsAPI Search results, the content detail page (also known as full result display), information fetched from Catalog, and responses are available either as XML or JSON. The parameter format is used to specify which type:&format=JSON&format=XMLIf not specified, JSON is the default.Pretty Printing the ResponseAdd the special parameter:&pretty=trueTo pretty print the output with correct indentation, tags aligned, etc. The default is pretty=false to save network bandwidth on communications.Note: All of the examples in this document show pretty printed output even though the pretty=true parameter is not shown. This is to make this documentation more readable.General Response StructureThis section discusses the standard response structure returned by Catalog.OPA will return the standard HTTP response code (e.g. 200, 400, 401, 404, etc.) in the response headers and will also return more detail on the response in the response data.Response CodesAll APIs will return the following standard HTTP response codes:200 – OK400 – Bad Request (bad parameters specified)401 – Unauthorized (attempted to perform a function without logging in first, OR attempted to modify someone else’s data)404 – Not Found (when the URL path is poorly formed, or when one of the identifiers specified in the URL is not found)500 – OPA internal server errorResponse DataSome API requests will simply return the content directly. For example, GET’ing a movie will simply stream the bytes of the movie back as the API response data.But API methods which do something (save a transcription, for example) or list things (e.g. search) will return an <opa-response> tag with the following sub-elements:header – Holds information about the request, including:@status – The HTTP status code@time – The time the system spent handling the requestrequest – Request information including the following sub-elements:@path – The path requestedRequest parametersThese will be name/value pairs, one for every parameter included in the request.Note that some parameters will be purposefully removed (such as password), or any parameter which is not a legal XML tag.error – Additional error information (if an error occurred), including the following sub-elements@code – The Catalog error code.This will be a string such as “INVALID_LIST” which can be used to construct an appropriate error message to the end user.A list of error codes returned by each call is listed in the documentation.Error parametersThese will be name/value pairs which provide additional data on the error which occurred.Note: Should any parameters not be legal characters for XML tags, they will be removed from the output.Results section [optional]What appears in this section varies based upon the API request. Some requests will not have results, only status.If there was an error, this section will not be present.OutlineThe following is a general outline of the header returned by most Catalog API calls:<opa-response><header status="HTTP Status" time="Time in ms"><request path="URL-path"><PARAM-NAME1>param-value1</PARAM-NAME1><PARAM-NAME2>param-value2</PARAM-NAME2><PARAM-NAME3>param-value3</PARAM-NAME3></request> <errors> <error code="ERROR-CODE"> <PARAM-NAME1>param-value1</PARAM-NAME1> <PARAM-NAME2>param-value2</PARAM-NAME2> <PARAM-NAME3>param-value3</PARAM-NAME3> </error> </errors></header> . . Results specific tags as defined later in this document goes here .</opa-response>XML Example<opa-response><header status="200" time="132"><request path="/iapi/v1"><action>search</action><q>kennedy</q><f.title>rose</f.title></request></header> . . The search results would be returned here .</opa-response>JSON Example{ "header":{ "@status":"200", "@time":"132", "request":{ "@path":"/iapi/v1", "action":"search", "q":"kennedy", "f.title":"rose" } }, . . The search results would be returned here .}AuthenticationSearch and viewing NARA content do not require authentication. However, any editing of annotations (tags, comments, transcriptions, and translations) will require a login.Login through CatalogAll registered OPA users will be able to log in directly to Catalog with a username and password. The API method is straightforward:GET:“https” is absolutely required. Logins through HTTP will be rejected.The credentials will be returned as a cookie in the HTTP headers AND in the login response (in a nested <credentials> tag). See section REF _Ref380511321 \r \h 1.6.4 for more information on the cookie response.For security reasons, the password parameter will not be returned in the response.The example login responses below only show whether or not the login was successful. A “400” (BAD REQUEST) error will be returned if login failed.XML Example Login Response<opa-response><header status="200" time="132"/><request path="/iapi/v1/login"><user>pnelson</user></request></header><credentials>7F8A29ECAA4326AC81329AFBB26649ACE</credentials></opa-response>JSON Example Login Response{"header": {"@status":"200","@time":"132","request": {"@path":"/iapi/v1/login","user":"pnelson"}},"credentials":"7F8A29ECAA4326AC81329AFBB26649ACE"}Login with Third Party Authentication [LOW PRIORITY – RELEASE 2]Login with a third-party credential will be done using the following URL:GET provider can be any of: “google”, “twitter”, or “facebook”. The token will be the login token returned by the provider’s authentication method.See the appendix (section REF _Ref380579096 \r \h 6.3) for detailed instructions and links to documentation on how to fetch the appropriate authentication token for each provider.Catalog will validate the login token and then will provide Catalog credentials which must be used for all future API calls.Note:“https” is absolutely required. Logins through HTTP will be rejected.The credentials will be returned as a cookie in the HTTP headers (see section REF _Ref380511321 \r \h 1.6.4 for more information) as well as in the response data (in the <credentials> tag, see example below).For security reasons, the authentication token parameter will not be returned in the response.The example login responses below only show whether or not the login was successful. XML Example Login Response<opa-response><header status="200" time="132"/><request path="/iapi/v1/login"><provider>google</provider></request></header><credentials>7F8A29ECAA4326AC81329AFBB26649ACE</credentials></opa-response>JSON Example Login Response{"header": {"@status":"200","@time":"132","request": {"@path":"/iapi/v1/login""provider":"google"}},"credentials":"7F8A29ECAA4326AC81329AFBB26649ACE"}Login Error CodesError CodeDescriptionParametersLOGIN_FAILEDThe username or password was specified incorrectly.NoneBAD_PROVIDERThe provider name was not one of “google”, “twitter” or “facebook”.NoneCORRUPTED_TOKENThe token provided does not appear to be in the expected encoding or format.NoneINVALID_TOKENThe token provided for a third-party authentication could not be validated.NoneSYSTEM_ERRORAn error occurred during login. Please try again later.NoneAcquiring Catalog CredentialsThe login credentials will be returned with the HTTP headers in response to a login request.Set-Cookie: _lopa=<credentials>The user of the Catalog APIs will need to save the cookie information so that it can be used for all future requests.Note that the cookie has a lifetime of a single browser session. When using the APIs, you should only keep the cookie in RAM, it should never be written to disk and re-used.Using Catalog CredentialsCredentials are reuired for any API method which modifies content (e.g. annotations) on Catalog. APIs requiring authentication are indicated with “Requires login” throughout this document./iapi/v1Using the Cookie: HTTP HeaderThe second method for specifying credentials is to send it as a “Cookie:” in the HTTP request headers:Cookie: _lopa=< credentials>Note that HTTP can be used (does not require HTTPS) after login.RegistrationRegistration will be handled with JSP pages built on the server side, and not through API calls.ConfigurationThe OpaAPI is a set of three maven projects which are:OpaAPI which is the web application that will process the requests made to the OPA API.OpaArchLib which is a library with the basic set of classes needed for OpaAPI and OpaExportServer. This is a dependency for both projects.OpaExportServer which is an independent JAVA application in charge of scheduling and creating exports of huge size.The OpaAPI and the OpaExportServer are projects that can be executed (in a server application or a java application), after the maven install command is run in both project, the follow file structure will be created:Config directory: This contains the application properties and configuration file.Resources directory: This contains the set of XSL file required for exports and content details, the files containing the whitelists and blacklist used for validating request parameters and the NaraDas file.Output container file: This can be the war container file for a latter deployment on a server application or the jar file for running the export server.In order to run these two components is necessary to set up the following variables as part of the JAVA variables passed to the application server or the java application.-Dgov.nara.opa.api.data=<opastorage and export parent directory>-Dgov.nara.opa.api.config=<config directory>-Dgov.nara.opa.api.resources=<resources directory>The data folder is used for pointing the parent directory where the opastorage and the output exports are located. Besides those three variables there is another variable which needs to be set up only in the export server.-Dgov.nara.opa.api.bin=<export server binary directory>StorageFile API and Export Server use both local and S3 based storage.Local storage in file system is used for the following:Configuration and system resource files (read only)Staging storage for export files (read/write)S3 storageAPI is composed by three maven projects:OpaAPI which is used for the following:Media file and metadata storage (read only)Finished export file storage (read/write)For media file streaming performance API uses CloudFront as media server.S3 and CloudFront require setting up connection and authorization values. These values are set in API and Export Server’sweb application.properties file. The settings are, in charge of handling the request sent to the following: OPA API.useS3Storage: (true/false) specifies whether or not S3 storage is active. If false, normal file system storage is used.s3BaseLocation: (path) specifies the S3 key prefix that all stored media and metadata elements will share.s3ExportsLocation: (path) specifies the export files location in S3.s3StorageBucketName: (string) the S3 bucket name.s3StorageAccessKeyId: (string) the S3 access key.s3StorageSecretKey: (string) the S3 secret key.useCloudFront: (true/false) whether or not CloudFront should be used for media streaming.cloudFrontDomainName: (url) the CloudFront server domain nameAccess APIThe Access API is used to download digital objects, get descriptive metadata, annotations and other information from OPA.The URL Path MapThe following map shows all of the possible paths available for the APIs. – all authority records (section 2.4)organizations/ – all metadata and annotations on the organization (section REF _Ref380589624 \r \h 2.4.2)<organization-id>/ – all metadata and annotations on the organizationorganization – just descriptive metadata on the organizationannotations/ – summary info for annotations on the org (sec. 4.2)comments – comments on the organization (sec. 4.3)tags – tags on the organization (sec. 4.4)people/ – all people authority records (section 2.4.1)<person-id>/ – all metadata and annotations on the personperson – just descriptive metadata on the specified personannotations/ – summary info for annotations on the person (sec. REF _Ref379804207 \r \h 4.2)comments – comments on a particular person (sec. 4.3)tags – tags on a particular person (sec. 4.4)holdings/ – all content and content related data (sec. REF _Ref379525675 \r \h 2.3)<NAID>/ – everything related to a single archival description (sec. REF _Ref379525359 \r \h 2.3.1)annotations/ – summary info on all annotations (sec. REF _Ref379804207 \r \h 4.2)comments – comments on archival descriptions (sec. 4.3)tags – tags on archival descriptions (sec. 4.4)content/ – all content files (sec. REF _Ref379525644 \r \h 2.3.1.4)description – descriptive metadata (sec. REF _Ref379525657 \r \h 2.3.1.1)objects/ – all information on digital objects in the NAID (sec. REF _Ref380583333 \r \h 2.3.1.2)<object-id>/ – information on a specific objectannotations/ – summary info for annotations on the content file (sec. REF _Ref379804207 \r \h 4.2)comments – comments on the content file (sec. REF _Ref379525620 \r \h 4.3)tags – tags on the content file (sec. REF _Ref381905623 \r \h 4.4)transcription – transcription of the content file (sec. REF _Ref381905799 \r \h 4.5)translations – all translated languages for the content file (sec. REF _Ref381905827 \r \h 4.6)opa-renditions/ – renditions of content files for UIs (sec. REF _Ref379525710 \r \h 2.3.1.5)thumbnails/ – holds all thumbnails of content filesimage-tiles/ – holds tiled image representations for image browsersusers/ – information about registered users on OPA (sec. REF _Ref378769256 \r \h 5)<user-id>/ – summary information on a specific user ID (sec. REF _Ref380767631 \r \h 5.1)account – profile information on the user (sec. REF _Ref380767782 \r \h 5.6)bulk-exports – information on bulk exports available or in progress (sec. REF _Ref380616157 \r \h 5.4)contributions/ – summary of all contributions by the user (sec. REF _Ref380615854 \r \h 5.2)contributedComments – comments made by the user (sec. REF _Ref380767658 \r \h 5.2.3)contributedTags – comments made by the user (sec. REF _Ref380767669 \r \h 5.2.4)contributedTranscriptions – transcriptions made by the user (sec. REF _Ref380767679 \r \h 5.2.5)contributedTranslations – translations made by the user (sec. REF _Ref380767687 \r \h 5.2.6)Note: The “contributed” prefixed on these paths is used to avoid confusion with the standard “comments”, “tags”, “transcriptions” and “translations” tags because the two sets of tags return different metadata structures.lists – lists of documents (“My Lists”) by the user (sec. REF _Ref379616946 \r \h 5.3)notifications – user notifications (sec. REF _Ref380616279 \r \h 5.5)web – allows for searching over web pages (sec. REF _Ref379443499 \r \h 3)Why use the Access API?We recommend using the Access API over using the Search API when you know the ID of a record to be fetched. The Access API will be faster than performing a search and will use fewer Catalog resources to complete the request.Other paths in will be other paths within used by the end-user interface, including: These paths are NOT part of the API and should NOT be used by users of the APIs to download content. Their functionality and content may change at any time without notice or an apology.Note, however, these URLs can be used to construct links for web pages, for any user interface that wishes to link to web pages served by the official Catalog user -Level Path – /iapi/v1The “” path will be used for executing searches across all Catalog content (holdings, authorities, and web sites).For more information on search features available, please see section REF _Ref379443499 \r \h 3.Holdings – /iapi/v1/idDescriptions of physical holdings and actual copies of on-line holdings can be downloaded from Catalog using paths which start with “”.You may also execute searches on this path, if you wish to limit your results to only documents from the “holdings” source. See section REF _Ref379443499 \r \h 3 for more details.The NAID – /iapi/v1/id/<NAID>All Catalog holdings are accessed using the “NARA Identifier” (NAID). A unique NAID is assigned to every collection, record group, series, file unit, and item inside of NARA. All holdings receive an NAID, regardless of whether the holdings are on-line or only available by visiting a NARA facility.Notes:The NAID is an integer – For example “7226539”The number ranges from 1 to approximately 8 million.The NAID is stable – Once assigned to a description it will never changeAll descriptions at all levels have an NAIDRecord groups, collections, series, file units, and itemsExamples:“Letter from George McGovern to Harry S. Truman, 08/19/1972” (Item)NAID = 7226539“Subject Files, 1953 – 1972” (Series)(from the Harry S. Truman Post-Presidential Papers, 1953 – 1973)NAID = 201502“Harry S. Truman Post-Presidential Papers, 1953 – 1973” (Collection HST-PPP)NAID = 1204How do I find the NAID?There are two methods:Search using the public Catalog web site: .When you find a record that you need, view the record and the “National Archives Identifier” (NAID) will be clearly identified in the search results and on the content detail page.Perform a search with the Search API. See section REF _Ref379518840 \r \h 3.All archival descriptions will have a “naid” field that you can use to locate and download content.All objects will have a “parentNaid”.This is also an NAID that can be used to locate and download content.The NAID ContentsThe contents of a NAID on Catalog are gathered together into a construct called an “OPA?Information Package” (OPA-IP) which serves as a holder for all content and metadata related to the archival description identified by the NARA ID.When the NAID can be fetched directly, using a path such as:GET will return a summary of all of the information contained in the NAID, appropriate for presentation in a content-detail representation. This information will include:<description> – The complete archival description (section REF _Ref379525657 \r \h 2.3.1.1)<objects> – An inventory of the objects and files contained within the NAID (section REF _Ref380583333 \r \h 2.3.1.2)<annotations> – A summary of the annotations contained within the NAID (section REF _Ref379804207 \r \h 4.2)XML ExampleGET naid="7226539"> <description> . . The archival description goes here. See section REF _Ref379525657 \r \h 2.3.1.1 . </description> <objects version="OPA-OBJECTS-1.0" count="3" created="2014-03-14T13:44:34"> . . The archival description goes here. See section REF _Ref380583333 \r \h 2.3.1.2 . </objects> <annotations> . . A summary of the annotations on this description will go here (section REF _Ref379804207 \r \h 4.2) . </annotations></opa-ip>JSON ExampleGET{ "@naid":"7226539", "description":{ . . The archival description goes here. See section REF _Ref379525657 \r \h 2.3.1.1 . }, "objects":{ "@version":"OPA-OBJECTS-1.0", "@count":"3", "@created":"2014-03-14T13:44:34", . . The archival description goes here. See section REF _Ref380583333 \r \h 2.3.1.2 . }, "annotations":{ . . A summary of the annotations on this description will go here (section REF _Ref379804207 \r \h 4.2) . }}description – /iapi/v1/id/<NAID>/descriptionUse this path to download the descriptive metadata for the archival description. The default representation will be XML. The format can be specified as a query parameter to download a JSON representation of the description like /iapi/v1/id/<NAID>/description?format=json.For more information about the archival description XML provided by Catalog, please see [TBD – is there documentation on this XML format from NARA?].Note: The <objects> tag will be removed from the <archival-description> document. Instead, use the <objects> from the objects inventory see section REF _Ref380583333 \r \h 2.3.1.2, which contains more information.XML ExampleGET version = '1.0'?><description> <arc-id>863</arc-id> <arc-id-desc>863</arc-id-desc> <title>Eunice B. Haden Collection</title> <title-only>Eunice B. Haden Collection</title-only> <collection-id>HADEN</collection-id> <sequence-number>1</sequence-number> <created-timestamp>11/9/2013 1:13:20</created-timestamp> <edited-timestamp>[g_x16_795, g_x128_99, g_x2_6365, g_x64_198, g_x32_397, g_x8_1591, g_x4_3182, b_x1_12731]</edited-timestamp> <level-of-desc level-id="COL"> <lod-display>Collection</lod-display> </level-of-desc> <series-count>1</series-count> <title-date>1865 - 1865</title-date> <inclusive-dates> <inc-start-date>1865</inc-start-date> <inc-end-date>1865</inc-end-date> </inclusive-dates> <donors> <donor num="1" donor-record-type="PER" donor-id="8380485" standard="Y"> <donor-display>Haden, Eunice B.</donor-display> </donor> </donors> <variant-control-numbers> <variant-control-number num="1" mlr="false"> <variant-number>HADEN</variant-number> <variant-number-desc>HADEN</variant-number-desc> <variant-type>NAIL Control Number</variant-type> </variant-control-number> </variant-control-numbers> <physical-occurrences> <physical-occurrence> <copy-status>Preservation-Reproduction-Reference</copy-status> <reference-units> <reference-unit num="1" summary="true"> <ref-id>31</ref-id> <name>National Archives at College Park - Still Pictures</name> <address1>National Archives at College Park</address1> <address2>8601 Adelphi Road</address2> <city>College Park</city> <state>MD</state> <postcode>20740-6001</postcode> <mailcode>RD-DC-S</mailcode> <phone>301-837-0561</phone> <fax>301-837-3621</fax> <email>stillpix@</email> </reference-unit> </reference-units> </physical-occurrence> </physical-occurrences> <indexable-dates> <date-range>[g_x16_116, g_x4_466, b_x1_1865, g_x64_29, g_x2_932, g_x128_14, g_x32_58, g_x8_233]</date-range> </indexable-dates></description>JSON ExampleGET{ "arc-id":"863", "arc-id-desc":"863", "title":"Eunice B. Haden Collection", "title-only":"Eunice B. Haden Collection", "collection-id":"HADEN", "sequence-number":"1", "created-timestamp":"11/9/2013 1:13:20", "edited-timestamp":"[g_x16_795, g_x128_99, g_x2_6365, g_x64_198, g_x32_397, g_x8_1591, g_x4_3182, b_x1_12731]", "level-of-desc":{ "@level-id":"COL", "lod-display":"Collection" }, "series-count":"1", "title-date":"1865 - 1865", "inclusive-dates":{ "inc-start-date":"1865", "inc-end-date":"1865" }, "donors":{ "donor":{ "@num":"1", "@donor-record-type":"PER", "@donor-id":"8380485", "@standard":"Y", "donor-display":"Haden, Eunice B." } }, "variant-control-numbers":{ "variant-control-number":{ "@num":"1", "@mlr":"false", "variant-number":"HADEN", "variant-number-desc":"HADEN", "variant-type":"NAIL Control Number" } }, "physical-occurrences":{ "physical-occurrence":{ "copy-status":"Preservation-Reproduction-Reference", "reference-units":{ "reference-unit":{ "@num":"1", "@summary":"true", "ref-id":"31", "name":"National Archives at College Park - Still Pictures", "address1":"National Archives at College Park", "address2":"8601 Adelphi Road", "city":"College Park", "state":"MD", "postcode":"20740-6001", "mailcode":"RD-DC-S", "phone":"301-837-0561", "fax":"301-837-3621", "email":"stillpix@" } } } }, "indexable-dates":{ "date-range":"[g_x16_116, g_x4_466, b_x1_1865, g_x64_29, g_x2_932, g_x128_14, g_x32_58, g_x8_233]" }}objects – /iapi/v1/id/<NAID>/objectsEvery NAID that contains digital objects will have an inventory which lists all digital objects and all of their various renditions and annotations. The list of objects can be fetched with:GET default listing will not return any nested annotations with the objects, only a @hasAnnotations attribute.To return a summary of nested annotations (counts), use:GET return all nested annotations and all text, use:GET not Objects inside of <description>?The Objects XML is kept separate from the archival description for several reasons:It contains files which are not available in the Lifecycle Data Requirements Guide (LCDRG), including:Image tilesSearch Engine Data (se data)Transcriptions / TranslationsIt contains much more technical metadata than is available in the LCDRG.Image color models, resolutions, etc.Video frames per second, audio channels, etc.Number of pages per PDF, other document metadataIt is built by Catalog during ingestion and is maintained as transcriptions and translations are updated.Objects XML FormatThe fields in the objects.xml are as follows:@version – Specifies the type and version of the objects XML.The only version currently defined is “OPA-OBJECTS-1.0”@created – Date-time this inventory.xml file was first created.Note: Must be maintained as the file is updated.object – specifies a digital object This is a holder for multiple renditions and metadata for the objectEach <object> tag will have the following nested information:@id – The identifier for this object, unique across all objects within the same NAID.Note: This will be the stable DAS object ID for the object, for objects from DAS.For objects from SEIP, this will be a unique number for the object within the SEIP.@hasAnnotations – True if the object has annotations, false otherwise.description – This is a copy of the object’s description from the archival description.From the LCDRG: “Provides information about the Digital Object that is not apparent from Object Designator or Object Identifier”designator – This is a copy of the object’s designator from the archival description.From the LCDRG: “An identifier for each digital object when there is more than one digital object associated with an archival description.”file – Specifies the file which holds a copy or alternative representation of the content of the digital object. Has the following sub-elements:@type – The type of the file (only “primary” supported in 1.0)@mime – The MIME type of the file@path – The path to the file, relative to the NAID URL.technicalMetadata – Holds extracted metadata for the fileThe contents of the technical metadata section will vary based on the type of file. See the appendix (section REF _Ref380579287 \r \h 6.2) for detailed information on all of the technical metadata which is gathered for each different file type.thumbnail – Specifies the location of the thumbnail for the object.Note: This is only used for thumbnails which are an image of the actual content, and it may be missing. If missing, the mime type should be used to show an appropriate icon for the content in place of the thumbnail.Note that thumbnails are Catalog -generated for presentation purposes only and will not have technical metadata.Has the following sub-elements:@path – A path, relative to the NAID URL, for accessing the thumbnail.@mime – The mime type of the thumbnail.imageTiles – If the content represents an image, <imageTiles> will specify the location of a tiled version of the document which can be accessed by Open Seadragon.Has the following sub-elements:@path – The path, relative to the NAID URL, where the image tiles can be found. This is often a path to a directory where the individual tiled files can be accessed.@type – The format of the image tiles. Currently, only “DZI” is supported.seData – Holds search engine data for the object. This is additional extracted metadata for the file such as from/to/cc/bcc for E-mail files. This metadata will be specified as XML in the NARA SEIP (version 1) SE data format.Has the following sub-elements:@path – Specifies the path to the Search Engine metadata, relative to the NAID URL.@mime – The mime type of the SE data. Always “text/xml”.all se-data fields – Note that the <seData> tag will contain the entire metadata from the SE data file for the specified object.annotations – This is the parent tag for all annotations contained within the object. It contains the following sub-elements:comments – Lists all of the comments on the object, in the same format as described in section REF _Ref380763740 \r \h 4.3.1.tags – Lists the tags on the object, in the same format as described in section REF _Ref379829230 \r \h 4.4.1.transcription – If the object has a transcription, then the file name for the transcription will be specified, in the same format as described in section REF _Ref380941809 \r \h 4.5.1.Contains the following sub-elements:translations – Parent tag to hold the object translations, in the same format as described in section REF _Ref380879861 \r \h 4.6.1.XML ExampleGET version="OPA-OBJECTS-1.0" count="3" created="2014-03-14T13:44:34"> <object id="1" hasAnnotations="true"> <designator>1</designator> <file type="primary" path="./content/hst-ppp_93-1_18-01.jpg" mime="image/jpeg"> <technicalMetadata> <createDate>2012-10-22T03:26:34Z</createDate> <metadataDate>2013-02-20T02:55:27Z</metadataDate> <modifyDate>2013-02-20T02:55:27Z</modifyDate> <size>1142680</size> <mime>image/jpeg</mime> <dimensions width="2181" height="2781"/> <resolution x="300" y="300" units="pixels/inch"/> <bitsPerSample>8 8 8</bitsPerSample> <photometricInterpretation>RGB</photometricInterpretation> <orientation>horizontal</orientation> <samplesPerPixel>3</samplesPerPixel> <planarConfiguration>chunky</planarConfiguration> <colorSpace>sRGB</colorSpace> <compression>uncompressed</compression> <software>Adobe Photoshop CS6 (Windows)</software> </technicalMetadata> </file> <thumbnail path="./opa-rendition/thumbnails/hst-ppp_93-1_18-01-thumb.jpg" mime="image/jpeg"/> <imageTiles path="./opa-rendition/image-tiles/hst-ppp_93-1_18-01_jpg"/> <annotations> <comments comments="3" replies="2" total="5"> <comment id="19328" user="kmartin" created="2014-02-10T14:36:23" lastModified="2014-02-10T14:40:12"> <text>One wonders if this letter to Frm Pres. Truman was felt to be obligatory, or if there was real affection between the two.</text> <replies> <reply id="45239" user="mstewart" fullName="Meredith Stewart" naraStaff="true" created="2014-02-10T15:00:03"> <text>True, but from different generations.</text> </reply> <reply id="45422" user="mkoneni" created="2014-03-08T04:12:52" lastModified="2014-03-08T04:18:02"> <text>I'm sure they ran into each other a bunch, you know at charity functions and golf tournaments...</text> </reply> </replies> </comment> <comment id="19102" user="tjefferson" created="2014-03-08T04:12:52" isDeleted="true"/> <comment id="17024" user="rbarnes" created="2014-03-09T11:14:27"> <text>Seems rather formulaic to me. I bet a staff member wrote it.</text> </comment> </comments> <tags total="3"> <tag text="Truman Post President" user="jdoe" created="2014-02-21T16:22:58"/> <tag text="McGovern Letters" user="agullet" created="2014-02-27T18:23:47"/> <tag text="nara:president=Truman" user="mstewart" fullName="Meredith Stewart" naraStaff="true" created="2014-03-19T07:07:42"/> </tags> <transcription lastModified="2014-02-21T16:22:58" isLocked="true" isauthoritative="false" version="232"> <lockedBy id="gwashington" when="2014-02-22T10:08:41"/> <users total="3"> <user id="tjefferson" fullName="Thomas Jefferson" isNaraStaff="true" lastModified="2014-02-21T16:22:58" /> <user id="mstewart" fullName="Meredith Stewart" isNaraStaff="true" lastModified="2014-02-08T12:59:49"/> <user id="kmartin" lastModified="2014-02-02T08:44:12" /> </users> <text>GEORGE McGOVERN United States Senate Washington, D.C. 20510 August 19, 1972 The Honorable Harry S. Truman Independence, Missouri My dear Mr. President: It is an honor for me, as our party's candidate for President of the United States. . .</text> </transcription> <translations total="3"> <translation code="ita" lastModified="2014-02-21T16:22:58" isLocked="true" isauthoritative="false" version="232"> <lockedBy id="gwashington" when="2014-02-22T10:08:41"/> <users total="3"> <user id="tjefferson" fullName="Tomás Jefferson" isNaraStaff="true" lastModified="2014-02-21T16:22:58" /> <user id="gwashington" fullName="Giorgio Washington" isNaraStaff="true" lastModified="2014-02-08T12:59:49"/> </users> <text>George McGovern Senato degli Stati Uniti Washington, D.C. 20510 19 ago 1972 L'Onorevole Harry S. Truman Independence, Missouri Mio caro Signor Presidente: E 'un onore per me, come il nostro partito di candidato alla Presidenza degli Stati Uniti. .</text> </translation> <translation code="spa"> . . Full information on the Spanish translation goes here . </translation> <translation code="deu"> . . Full information on the German translation goes here . </translation> </translations> </annotations> </object> <object id="2"> <designator>2</designator> <file type="primary" path="./content/hst-ppp_93-1_18-02.jpg" mime="image/jpeg"> <technicalMetadata> . . Technical metadata for the primary file for the second object will go here . </technicalMetadata> </file> <thumbnail path="./opa-rendition/thumbnails/hst-ppp_93-1_18-02-thumb.jpg" mime="image/jpeg"/> <imageTiles path="./opa-rendition/image-tiles/hst-ppp_93-1_18-02_jpg"/> </object> <object id="3"> <designator>3</designator> <file type="primary" path="./content/hst-ppp_93-1_18-03.jpg" mime="image/jpeg"> <technicalMetadata> . . Technical metadata for the primary file for the third object will go here . </technicalMetadata> </file> <thumbnail path="./opa-rendition/thumbnails/hst-ppp_93-1_18-03-thumb.jpg" mime="image/jpeg"/> <imageTiles path="./opa-rendition/image-tiles/hst-ppp_93-1_18-03_jpg" type="DZI"/> </object></objects>JSON ExampleGET{ "@version":"OPA-OBJECTS-1.0", "object":[ { "@id":"1", "@hasAnnotations":"true", "designator":"1", "file":{ "@type":"primary", "@path":"./content/hst-ppp_93-1_18-01.jpg", "@mime":"image/jpeg", "technicalMetadata":{ "createDate":"2012-10-22T03:26:34Z", "metadataDate":"2013-02-20T02:55:27Z", "modifyDate":"2013-02-20T02:55:27Z", "size":"1142680", "mime":"image/jpeg", "dimensions":{ "@width":"2181", "@height":"2781" }, "resolution":{ "@x":"300", "@y":"300", "@units":"pixels/inch" }, "bitsPerSample":"8 8 8", "photometricInterpretation":"RGB", "orientation":"horizontal", "samplesPerPixel":"3", "planarConfiguration":"chunky", "colorSpace":"sRGB", "compression":"uncompressed", "software":"Adobe Photoshop CS6 (Windows)" } }, "thumbnail":{ "@path":"./opa-rendition/thumbnails/hst-ppp_93-1_18-01-thumb.jpg", "@mime":"image/jpeg" }, "imageTiles":{ "@path":"./opa-rendition/image-tiles/hst-ppp_93-1_18-01_jpg" }, "annotations":{ "comments":{ "@comments":"3", "@replies":"2", "@total":"5", "comment":[ { "@id":"19328", "@user":"kmartin", "@created":"2014-02-10T14:36:23", "@lastModified":"2014-02-10T14:40:12", "text":"One wonders if this letter to Frm Pres. Truman was felt to be obligatory, or if there was real affection between the two.", "replies":{ "reply":[ { "@id":"45239", "@user":"mstewart", "@fullName":"Meredith Stewart", "@naraStaff":"true", "@created":"2014-02-10T15:00:03", "text":"True, but from different generations." }, { "@id":"45422", "@user":"mkoneni", "@created":"2014-03-08T04:12:52", "@lastModified":"2014-03-08T04:18:02", "text":"I'm sure they ran into each other a bunch, you know at charity functions and golf tournaments..." } ] } }, { "@id":"19102", "@user":"tjefferson", "@created":"2014-03-08T04:12:52", "@isDeleted":"true" }, { "@id":"17024", "@user":"rbarnes", "@created":"2014-03-09T11:14:27", "text":"Seems rather formulaic to me. I bet a staff member wrote it." } ] }, "tags":{ "@total":"3", "tag":[ { "@text":"Truman Post President", "@user":"jdoe", "@created":"2014-02-21T16:22:58" }, { "@text":"McGovern Letters", "@user":"agullet", "@created":"2014-02-27T18:23:47" }, { "@text":"nara:president=Truman", "@user":"mstewart", "@fullName":"Meredith Stewart", "@naraStaff":"true", "@created":"2014-03-19T07:07:42" } ] }, "transcription":{ "@lastModified":"2014-02-21T16:22:58", "@isLocked":"true", "@isauthoritative":"false", "@version":"232", "lockedBy":{ "@id":"gwashington", "@when":"2014-02-22T10:08:41" }, "users":{ "@total":"3", "user":[ { "@id":"tjefferson", "@fullName":"Thomas Jefferson", "@isNaraStaff":"true", "@lastModified":"2014-02-21T16:22:58" }, { "@id":"mstewart", "@fullName":"Meredith Stewart", "@isNaraStaff":"true", "@lastModified":"2014-02-08T12:59:49" }, { "@id":"kmartin", "@lastModified":"2014-02-02T08:44:12" } ] }, "text":"GEORGE McGOVERN\n United States Senate\n Washington, D.C. 20510\n\n August 19, 1972\n\n The Honorable Harry S. Truman\n Independence, Missouri\n\n My dear Mr. President:\n\n It is an honor for me, as our party's\n candidate for President of the United States. . ." }, "translations":{ "@total":"3", "translation":[ { "@code":"ita", "@lastModified":"2014-02-21T16:22:58", "@isLocked":"true", "@isauthoritative":"false", "@version":"232", "lockedBy":{ "@id":"gwashington", "@when":"2014-02-22T10:08:41" }, "users":{ "@total":"3", "user":[ { "@id":"tjefferson", "@fullName":"Tom?s Jefferson", "@isNaraStaff":"true", "@lastModified":"2014-02-21T16:22:58" }, { "@id":"gwashington", "@fullName":"Giorgio Washington", "@isNaraStaff":"true", "@lastModified":"2014-02-08T12:59:49" } ] }, "text":"George McGovern \n\n Senato degli Stati Uniti \n Washington, D.C. 20510 \n\n 19 ago 1972 \n\n L'Onorevole Harry S. Truman \n Independence,Missouri \n\n Mio caro Signor Presidente: \n\n E 'un onore per me, come il nostro partito di \n candidato alla Presidenza degli Stati Uniti. ." }, { "@code":"spa", . . Full information on the Spanish translation goes here . }, { "@code":"deu", . . Full information on the Spanish translation goes here . } ] } } }, { "@id":"2", "designator":"2", "file":{ "@type":"primary", "@path":"./content/hst-ppp_93-1_18-02.jpg", "@mime":"image/jpeg", "technicalMetadata":{ . . Technical metadata for the primary file for the second object will go here . } }, "thumbnail":{ "@path":"./opa-rendition/thumbnails/hst-ppp_93-1_18-02-thumb.jpg", "@mime":"image/jpeg" }, "imageTiles":{ "@path":"./opa-rendition/image-tiles/hst-ppp_93-1_18-02_jpg" } }, { "@id":"3", "designator":"3", "file":{ "@type":"primary", "@path":"./content/hst-ppp_93-1_18-03.jpg", "@mime":"image/jpeg", "technicalMetadata":{ . . Technical metadata for the primary file for the second object will go here . } }, "thumbnail":{ "@path":"./opa-rendition/thumbnails/hst-ppp_93-1_18-03-thumb.jpg", "@mime":"image/jpeg" }, "imageTiles":{ "@path":"./opa-rendition/image-tiles/hst-ppp_93-1_18-03_jpg", "@type":"DZI" } } ]}annotations – /iapi/v1/contributions/summary/id/<NAID>Use this URL to get summary information on all of the annotations for the specified NAID.This will include all of the tags (with metadata) and all of the comments (with metadata), plus all summary information on the existence of transcriptions and translations.See section REF _Ref379804207 \r \h 4.2 for more ments – /iapi/v1/id/<NAID>/commentsUse this URL to access information on comments attached to an archival description. Within this path, you can access three types of data:comments – The list of all comments and replies attached to the descriptionThis includes all comment and reply metadata (creator, creation date, etc.)comments/<comment-id> - A single comment with all repliesThis includes all comment and reply metadata (creator, creation date, etc.)comments/<reply-id> - A single reply to a single commentThis includes all reply metadata (creator, creation date, etc.)More information on comments can be found in section REF _Ref379520189 \r \h 4.3.tags – /iapi/v1/id/<NAID>/tagsUse this URL to access tags attached to an archival description. Within this path you can access two types of information:tags – The list of all tags attached to the descriptionThese are sorted alphabeticallyEach tag is returned with metadata such as who created the tag, the date of the tag, etc.tags?text=<tag-text> – Retrieves information about a single tagThis includes all tag metadata (creation date, creator, etc.)More information about tags can be found in section REF _Ref381905623 \r \h 4.4.content – /iapi/v1/media/<NAID>/ The content directory holds content files which can be downloaded. Content files include:Scanned images of physical itemsFor example, scans of documents, posters, maps, etc.Digital renditions of analog contentFor example, digital video of news reels, digital audio of content on reel-to-reel analog audio tapeCopies or renditions of born-digital contentFor example, E-mail files in XML, MS-Word or MS-Excel documents, digital photographs from digital cameras, digital video from digital camcorders, digital audioCopies or renditions of database filesMuch content in NARA is in the form of large tables of information from Government computer systems.These tables (sometimes in various formats) can be downloaded in bulk for off-line analysis.Technical documentationUsually PDFs, often from paper documents, which describe the contentHow do I get the Full Path to a Content File?After the content path, you must specify a particular file or path to a file in order to fetch a file from Catalog. For example:GET rare, it’s possible for files to be embedded inside sub-directories within a content directory:GET list of available content files can be found by accessing the NAID inventory of objects. For example:GET return a list of all of the digital objects in the “72265639” package, with all of the various renditions for each. See section REF _Ref381136677 \r \h 2.3.1.2 above for more information.Alternatively, you can directly search for all digital objects in NARA using . Search API results will contain URLs to the content files, thumbnails, etc.See section REF _Ref379525408 \r \h 3 below for more information on the search API.Content File AnnotationsEvery file in Catalog can be annotated with tags, comments, transcriptions or translations. While not all annotations are appropriate for every digital object, the API makes no distinction (any type of diogital object can be annotated – note: this may change in a future version).Digital object annotations can be downloaded, created, and updated by adding the appropriate suffix to the end of the content file path:GET section REF _Ref379804207 \r \h 4.2 for more information on annotations summary information.GET section REF _Ref379556191 \r \h 4.3 for more information on comments.GET section REF _Ref381905623 \r \h 4.4 for more information on tags.GET section REF _Ref381906191 \r \h 4.5 for more information on transcriptions.GET section REF _Ref381906208 \r \h 4.6 for more information on translations.opa-renditions – /iapi/v1/media/<NAID>/opa-renditionsThe “opa-renditions” path contains additional renditions of the content for use by Catalog user interfaces (and also available for other interfaces as well). These renditions are created by Catalog content processing system from the original content. The renditions include:GET thumbnail images of image files in the content directoryLater releases may contain thumbnail images of PDFs and video files as well.GET image tiles for lower-bandwidth browsing of very-high resolution photographs. Image tiles can be used by the OpenSeadragon tool.How do I get the Full Path to an OPA Rendition?The full paths for OPA renditions of content files can be acquired in two ways:Get the list of all objects for an OPA package (section REF _Ref381136677 \r \h 2.3.1.2).Perform a search with the search API for content files (section REF _Ref379559434 \r \h 3).The thumbnail and tiles filenames are available as fields in the search results.Authority Records – /iapi/v1/idAuthority records contain authoritative information about people and organizations. “Authoritative information” usually means the official name, alternative names, dates, and description of a person or an organization.Authority records can be accessed by type (“people”, “organizations”) and by ID.How do I Get a Person ID or Organization ID?There are two methods for getting a person or organization ID:Authority Record IDs are available in the archival description (section REF _Ref379525657 \r \h 2.3.1.1)For example, in section REF _Ref379525657 \r \h 2.3.1.1 the @donor-id attribute references a person ID.You can use the Search API to search for authority records (section REF _Ref379562132 \r \h 3)The search fields will contain authority record ID and authority record typePeople – /iapi/v1/id/<person-id>Authority record metadata and annotations for people can be directly accessed from Catalog using the person ID.Accessing this URL directly will fetch the following for the person:<person> – The person metadata (section REF _Ref380594513 \r \h 2.4.1.1 below)<annotations> – All annotations (comments and tags) on the record (section REF _Ref380594531 \r \h 2.4.1.2 below).XML ExampleGET type="person" id="1090294"> <person> . . Authority record metadata on the person goes here, see section REF _Ref380594513 \r \h 2.4.1.1 . </person> <annotations> . . Annotations attached to the person go here, see section REF _Ref379804207 \r \h 4.2. . </annotations></authority>JSON ExampleGET{ "@type":"person", "@id":"1090294", "person":{ . . Authority record metadata on the person goes here, see section REF _Ref380594513 \r \h 2.4.1.1 . }, "annotations":{ . . Annotations attached to the person go here, see section REF _Ref379804207 \r \h 4.2. . }}Person MetadataTo fetch just the person metadata, use <person-id>/person to access the information.For more information about the metadata returned for people authority records returned by Catalog, please see [TBD – is there documentation on this XML format from NARA?].XML ExampleGET; <person-id>1090294</person-id> <display-name>Seward, William Henry, 1801-1872</display-name> <preferred>Y</preferred> <date-of-birth>1801</date-of-birth> <date-of-death>1872</date-of-death> <source-note>His Alaska Speech ... Aug. 1869NUCMC data from NJ Hist. Soc. for Congar, H.N. Papers, 1863-1905 (William H. Seward, Sec. of State)WwWA, 1607-1896 (Seward, William Henry, 1801-1872; U.S. Sen., Sec. State; s. Dr. Samuel &amp; Mary (Jennings) Seward; m. Frances Miller; law practice &amp; res., Auburn, N.Y.; gov. N.Y., 1838-42; memb. U.S.Sen., 1849-1868; sec. state under Lincoln; negot. Alaska purchase, 1867)Dict. of U.S. history, 1931 (Seward, William Henry, 1801-1872; gov. N.Y. 1839-1843)</source-note> <created-timestamp>11/3/2013 23:18:48</created-timestamp> <index-character>s</index-character> <related>11</related> <donations>0</donations> <creations>0</creations> <contributions>4</contributions> <subject-of>7</subject-of> <staff-member>1</staff-member></person>JSON ExampleGET{ "person-id":"1090294", "display-name":"Seward, William Henry, 1801-1872", "preferred":"Y", "date-of-birth":"1801", "date-of-death":"1872", "source-note":"His Alaska Speech ... Aug. 1869\nNUCMC data from NJ Hist. Soc. for Congar, H.N. Papers, 1863-1905 (William H. Seward, Sec. of State)\nWwWA, 1607-1896 (Seward, William Henry, 1801-1872; U.S. Sen., Sec. State; s. Dr. Samuel & Mary (Jennings) Seward; m. Frances Miller; law practice & res., Auburn, N.Y.; gov. N.Y., 1838-42; memb. U.S.Sen., 1849-1868; sec. state under Lincoln; negot. Alaska purchase, 1867)\nDict. of U.S. history, 1931 (Seward, William Henry, 1801-1872; gov. N.Y. 1839-1843)", "created-timestamp":"11/3/2013 23:18:48", "index-character":"s", "related":"11", "donations":"0", "creations":"0", "contributions":"4", "subject-of":"7", "staff-member":"1"}People AnnotationsTags and comments can be accessed, added, removed, or updated to any person authority record, using the following paths:GET section REF _Ref379804207 \r \h 4.2 for more information on annotations summary information.GET section REF _Ref379562572 \r \h 4.3 for more information.GET section REF _Ref381905623 \r \h 4.4 for more anizations – /iapi/v1/id/<org-id>Authority records for organizations can be accessed directly from Catalog with the specified path.Accessing this URL directly will fetch the following for the organization:<organization> – The organization metadata (section REF _Ref380595645 \r \h 2.4.2.1 below)<annotations> – All annotations (comments and tags) on the record (section REF _Ref380595652 \r \h 2.4.2.2 below).XML ExampleGET type="organization" id="142876"> <organization> . . Authority record metadata on the organization goes here, see section REF _Ref380595645 \r \h 2.4.2.1 . </organization> <annotations> . . Annotations attached to the organization go here, see section REF _Ref379804207 \r \h 4.2. . </annotations></authority>JSON ExampleGET{ "@type":"organization", "@id":"1090294", "organization":{ . . Authority record metadata on the organization goes here, see section REF _Ref380595645 \r \h 2.4.2.1 . }, "annotations":{ . . Annotations attached to the organization go here, see section REF _Ref379804207 \r \h 4.2. . }}Organization Metadata – /iapi/v1/id/<orgid>/organizationWhen you need just the organization metadata (and not the annotations), you can fetch it with “id/<org id>”.For more information about the metadata returned for organization authority records returned by OPA, please see [TBD – is there documentation on this XML format from NARA?].XML ExampleGET; <organization-id>142876</organization-id> <display-name>Canadian Meteorological Service.</display-name> <preferred>Y</preferred> <source-note>CREATED FROM LCNAF CONVERSION</source-note> <created-timestamp>11/4/2013 17:24:57</created-timestamp> <index-character>c</index-character> <related>0</related> <organization-names> <organization-name org-name-id="142876"> <name>Canadian Meteorological Service.</name> <related>0</related> <donations>0</donations> <creations>0</creations> <contributions>0</contributions> <subject-of>0</subject-of> <predecessors> <predecessor num="1" predecessor-id="1055883" standard="Y"> <predecessor-display-name>Canada. Meteorological Branch</predecessor-display-name> </predecessor> </predecessors> <successors> <successor num="1" successor-id="1055884" standard="Y"> <successor-display-name>Canada. Atmospheric Environment Service</successor-display-name> </successor> </successors> </organization-name> </organization-names></organization>JSON ExampleGET{ "organization-id":"142876", "display-name":"Canadian Meteorological Service.", "preferred":"Y", "source-note":"CREATED FROM LCNAF CONVERSION", "created-timestamp":"11/4/2013 17:24:57", "index-character":"c", "related":"0", "organization-names":{ "organization-name":{ "@org-name-id":"142876", "name":"Canadian Meteorological Service.", "related":"0", "donations":"0", "creations":"0", "contributions":"0", "subject-of":"0", "predecessors":{ "predecessor":{ "@num":"1", "@predecessor-id":"1055883", "@standard":"Y", "predecessor-display-name":"Canada. Meteorological Branch" } }, "successors":{ "successor":{ "@num":"1", "@successor-id":"1055884", "@standard":"Y", "successor-display-name":"Canada. Atmospheric Environment Service" } } } }}Organization Annotations – /iapi/v1/id/<orgid>/annotationsTags and comments can be accessed, added, removed, or updated to any organization authority record, using the following paths:GET section REF _Ref379804207 \r \h 4.2 for more information on annotations summary information.GET section REF _Ref379562572 \r \h 4.3 for more informationGET /<org-id>/tagsSee section REF _Ref381905623 \r \h 4.4 for more informationUser Information – /iapi/v1/accountsInformation on users can be downloaded directly from Catalog with the user login ID (for example “kmartin”).Note: Much of what is available within the user URLs will vary depending on who is logged in.Users who are logged will have more complete access to their own user information than they will for other users.The following URLs are available to acquire user information:GET; User account information. See section 5.6 for details.GET on bulk exports either in progress or being created for the user. See section 5.4 for details.GET on contributions made by the user. See section 5.2 for details.GET on contributions made by the user. See section 5.2.3 for details.GET on contributions made by the user. See section 5.2.4 for details.GET on contributions made by the user. See section 5.2.5 for details.GET contributions/translations?username=<username>Information on contributions made by the user. See section 5.2.6 for details.GET on lists of search results saved by the user. Section 5.3 for details.GET on notifications for the user. Currently, notifications include events such as replies, edits to transcriptions, translations, and moderator actions which concern the user. Section 5.5 for details.Search APIThe heart of the OPA system is a powerful search engine capable of searching over all of the archival descriptions, on-line content and authority records which are available from Catalog.SearchingThe Search API can be used to search over different data sources:To search over everything:GET search over holdings: (archival descriptions and digital objects)GET search over authority records:GET search over web pages:GET Search API can also be used to create exports of search results:POST ListsFinally, the Search API can also be used to save results to lists.To save results to a new list:POST add results to an existing list:POST the search API, you specify query terms, filters, and the scope of the search as parameters, and the search engine will return results. Each result will contain metadata fields about the item.In addition to results, the search API can also do the following:Highlights – These are highlighted search keywords found in the field content.Facets – These are histograms of field metadata values (for certain fields only) which can be used to sub-set the results (also called “guided navigation”).Save results for bulk export – This allows you to bulk export metadata and content from Catalog into compressed files (tar.gz) which can be efficiently downloaded.Bulk exports are processed in the background.Save results to list – Results can be saved to a list to be individually examined later.One step search and process – Allows you to perform any of the access or annotation functions on the first result returned by a searchSearch Results EntriesThe following can be returned as individual entries in the search results:Archival Descriptions – Descriptive metadata about every collection, record group, series, file unit, and item available from NARA.Authority Records – Authoritative information about people and organizations which may be referenced by archival descriptions.Digital Objects – Files which represent the on-line content (and technical documentation about the on-line content) can be individually retrieved using the Search API.How Do I: Search for Archival Descriptions?Filter on type = “description”:GET Do I: Search for Digital Objects?Filter on type = “objects”:GET Do I: Search for Both?Filter on type = “description,object”:GET, filter on source = “holdings”:GET, restrict your scope to holdings:GET Do I: Retrieve all Digital Objects for a Description?Filter on naid=<ID of the description> and type=object:GET Do I: Search for Authority Records?Filter on source = “authorities”:GET, restrict your scope to “authorities”:GET Do I: Search for everything?Have no filter at all:GET Do I: Search for everything, but return web pages separately?Have no filter, but group by descriptions and web pages:GET annotations are not indexed as separate entries in the search engine index, but instead are indexed with the item (Description, Authoriy Record or an object) to which they are attached.Since the search engine can return descriptions, digital objects, authority records, and web pages as search results, annotations will be returned as fields inside each search result.The search API can:Locate all descriptions, digital objects, or authority records which contain:A particular tagSpecified query terms in any tag or tagsAny tag created by a specified user IDSpecified query terms in any comment or replyComments or replies by a specific user IDLocate all digital objects which contain:Specified query terms in a transcription or translationTranscriptions or translations originated by a particular user IDTranscriptions or translations edited by a particular user IDThe search API cannot:List all annotations by a particular user IDUse the contributed comments API for comments by user, section REF _Ref380854906 \r \h 5.2.3.Use the contributed tags API for tags by user, section REF _Ref380854889 \r \h 5.2.4.Use the contributed transcriptions API for transcriptions by user, section REF _Ref380854939 \r \h 5.2.5.Use the contributed translations API for translations by user, section REF _Ref380854958 \r \h 5.2.6.However, the search API can return a list of descriptions, digital objects, or authority records which contain a contribution by a particular user ID.List all comments or replies which contain specified query wordsHowever, the search API can return a list of descriptions, digital objects, or authority records which contain the specified query words in their comments.List all tags which contain specified query wordsHowever, the search API can return a list of descriptions, digital objects, or authority records which contain the specified query words in their tags.List all unique tagsTags can be returned by person, description, digital object, or authority record.Use the tagging API to get tags for descriptions, digital objects, or authority records, see section REF _Ref381907126 \r \h 4.4.A single list of all available tags is not anticipated for Catalog production (first?release)List all commentsComments can be returned by person, description, digital object, or authority?record.A single list of all comments is not anticipated for Catalog productionSearch FunctionsThe Catalog search API provides a number of capabilities:High-quality relevancy ranked keyword text search of content and selected metadata fieldsKeyword text search of any public, indexed, metadata fieldSome fields which are highly transient in nature (e.g. counts) may not be indexed and searchable [TBD]Computing a ‘relevancy score’ for all search results, based on how well the document matches the queryBoolean queries with AND, OR, and NOTRange searches such as locating documents with a specified date or integer rangeFiltering results based on keywords found in metadata or content fieldsSpecifying fields to return, in addition to default fieldsFields may also contain URLs to other pages, such as content detail pages, content, thumbnails, etc. as appropriateFaceting over metadata fieldsFaceting provides a histogram of the count of search results which contain specified field valuesFaceting is available over Data Source, Level of Description, Type of Materials, File Format, Location, and DateSorting of search resultsThe default sort order is by relevancy in descending orderSome fields (as specified in the DMD) may also be used for sortingSorting can be done over multiple fields as well as relevancy with the same API call (e.g., primary sort, secondary sort, etc.)Grouping of search resultsSeveral different methods are availableSuggested query terms from a Catalog thesaurusHighlighting of query term matches within the contentReturn of “best bets” or “featured holdings” which match a specified queryThese special results are also referred to as “search optimization”Search results list pagination, including returning a specified page or range of resultsResult set management (aka “lists”) - requires loginSave a search results list (up to a system defined maximum) to a named list in the user’s account.For more information, see section REF _Ref379616946 \r \h 5.3Bulk export of search results (requires login)May include digital objects associated with the search results as wellOne-step “Search and Process”To download or annotate the first result returned by a searchSearch API ParametersAll searches provided by the search API begin with one of the following URLs:GET parameters. . .GET parameters. . .GET parameters. . .GET parameters. . .Parameters for the search API are given in the following table.ParameterDescriptionExamplesaction=search|searchTag|searchWithin|contentDetailSpecifies the type of search to do and what to do with the search results.search – Perform a standard search and return the resultssearchTag – Perform a search with the supplied tagsearchWithin – Perform a search for all records which are descendants of a description.contentDetail – Perform a standard search and return the results and the content detail xsl for the first result.action=searchaction= searchTagaction= searchWithinsource=source1, source2,source3, . . .Specifies what major sources to search. Sources can be any of:authorities – Authority records for people and organizations.holdings – Descriptions and digital objects.web – web pages and presidential library web pages.If no “source” parameter is specified, Catalog will search over all sources.source=holdingssource=authorities,holdingstype=type1,type2,type3, . . .Specifies a list of result types to search. Types can be any of:description – All archival descriptionsobject – Digital objects (files)person – People authority recordsorganization – Organization authority recordsarchivesWeb – Web pages from .presidentialWeb – Web pages from presidential libraries.If no “type” parameter is specified, Catalog will search over all types.type=descriptiontype=description,object,archivesWebnaIds=naId1, naId2, naId3 . . .Specifies a list of NAIDs to search over.naIds=7238423,536932,4562889,3552324opaIds=opaId1, opaId2, opaId3. . .Specifies a list of OPA-IDs to search over.opaIds=desc-7238423,person-98824,org-889242,desc-7238423/32format=json|xmlSpecify the format of the results, either “json” or “xml”. Default is “xml”format=jsonformat=xmlSimple Keyword Queriesq=query expressionKeyword search over the full-text content (and selected full-text fields such as title).Full query expressions can be used as the value for ‘q’. See section REF _Ref380963664 \r \h 3.3 for more details.The ‘q’ parameter is optional. When missing, the search results will be based entirely on the filter parameters below.The exact list of fields which will be searched by the ‘q’ parameter will be different for each different type of content source, but usually includes the full content of the item plus high-quality full text fields such as ‘title’, ‘description’, etc.See the appropriate Data Model Definition (DMD) document for each source to identify exactly what fields are searched by ‘q’.q=Navyq=Kennedy and NASAq=kennedy missile crisisq= johnson and space and (nasa or "space agency")Parametric Searches / Filter Queriesfilter=query expressionFilters will restrict the scope of the search results to data which is in the specified fields.The bare “filter” parameter allows you to enter any arbitrary filter query expression including field: operators.The full query expression language can be found in section REF _Ref380963665 \r \h 3.3.filter=title:kennedy and level:(series or fileUnit)f.keywordField=query expressionf.keywordField is used to restrict results for keyword fields. It can be used for any type of “keyword” field specified in section 3.4.The query expression can be any expression specified in section 3.3.1.f.title=JFKf.title=campaign and (JFK or LBJ)f.stringField=query expressionf.stringField is used to restrict results for string fields. It can be used for any type of “string” field specified in section 3.4.“string” fields differ from keyword fields in that individual words within the field cannot be searched. The entire string value must be specified. String fields are typically for identifiers and when searching for exact tag values.The query expression can be any expression specified in section REF _Ref379718796 \r \h 3.3.2.f.opaId=desc-72232422f.opaId=desc-72232422 or desc-83343533f.dateField=date expressionf.dateField is used to restrict results based on a date or date range. It can be used for any type of date field specified in section 3.4.See section REF _Ref379623700 \r \h 3.3.3 for date expressions available to search date fields.f.inclusiveStart= range(1900,1999)f.inclusiveStart=2000f.inclusiveStart= range(1980-01-01, 1980-06-30)f.intField=int expressionf.intField is used to restrict results based on an integer or integer range. It can be used for any type of integer field specified in section 3.4.Integer expressions can use operators specified in section 3.3.4.f.inclusiveStartYear= range(1900,1999)f.inclusiveStartYear=2000f.boolField=true/falsef.boolField is used to restrict results for boolean fields. It can be used for any type of boolean field specified in section 3.4.Only “true” or “false” can be specified for boolean filter fields.f.hasOnlineContent=truef.hasChildren=falsef.fieldXml.tags=query expressionf.fieldXML.tags is a special expression used to search XML content. In this parameter, replace “fieldXml” with an XML field (see sections REF _Ref379836852 \r \h 3.4.7 or REF _Ref379836854 \r \h 3.4.8) and then replace “tags” with one or more XML tags separated by periods.For example:f.description.variant-numberSearches all <variant-number> tags in the description.f.description.creator.creator-typeSearches all <creator-type> tags found within <creator> tags in the descriptionf.description.variant-number="NWDNS-179-WP-1565"Controlling the OutputresultFields=field1, field2,field3, . . .List of fields to return in the result set.If a field is given that cannot be put in the return (such as a field that does not exist), an error is returned.Content within XML fields can be individually returned by specifying the tag (or sub-tag or attribute) with “field.tag.tag” notation.XML fields will be returned either as JSON or XML, depending on the setting of the “format” parameter.If no fields are specified, the following fields are returned automatically: source, type, naId, opaId, url, accessPath, localId, hmsEntryNumbers, containerId, iconType, title, titleDate, parentLevel, parentTitle, creators, and thumbnailFile.Note: If resultFields is missing, all fields in the index entry are returned.resultFields=title,urlresultFields=descriptionresultFields=description.subject-reference.display-nameresultFields=title,url,objects.object.annotations.transcriptionhighlight=true/falseTurn on highlighting of query term matches.highlight=truehighlight.fields=field1, field2, . . .If highlighting is on, this parameter identifies which fields to highlight.If an invalid field name is used, an error is returned.If no fields are specified and highlight=true, highlights will be returned for “content”, “title”, and “creator”.Only fields identified as “keyword” in section REF _Ref379621132 \r \h 3.4 can be specified as a highlight field.highlight.fields=titlehighlight.fields=title, content, creatorsgroup=groupTypeIndicates if the results should be grouped or not, and how the results should be grouped. Values allowed are:web – Group web results. Leave all other results as un-grouped.If not specified, a single flat list of results is returned.group=websort=field1 [asc|desc],field2 [asc|desc],. . . Sorts results based on field values. Specify the field to sort by followed by “asc” for ascending or “desc” for descending. Use the special field “score” (only available in sorting) to sort by relevancy.If not specified, the default sort is “score desc”.If a field name is given that cannot be sorted, an error is returned. If an invalid sort type is given, an error is returned.See section REF _Ref379621132 \r \h 3.4 for fields which can be used for sorting.sort=localId ascsort=localId asc, score descrows=#Indicates the number of search results to fetch. The default is 25.Note that different maximum values for “rows” may apply depending on what is done with the search results. [All values below TBD]For simple searches, “rows” is limited to 200.For saving search results to a list (see section REF _Ref379616946 \r \h 5.3), “rows” is limited to 1000.For exporting bulk results, “rows” is limited to 10000.rows=50offset=#The zero-based offset into the search results of the first result to be returned. This parameter is used in combination with ‘rows’ to paginate the results. If missing, the default offset is 0.If an offset less than 0 or greater than the maximum [Maximum TBD – based on type of user] is specified, an error is returned.offset=100 facet=true/falseEnable faceting so that counts are returned. Facets are essentially histograms of the values which occur in specified fields.facet=truefacet.fields=fieldSpecifies the list of fields for which facet values are returned.If not specified and facet=true, then facets will be automatically returned for source, type, level, fileFormat, materialsType, dateRangeFacet, and locationIds.If a field is given that cannot be used for faceting, an error is returned. See section REF _Ref379621132 \r \h 3.4 for fields which can be used for faceting.facet.fields=level,fileFormatfacet.stringField=query expressionfacet.stringField is for filtering results by facet values. It operates exactly the same as f.stringField, but is provided with a separate parameter name to help clients distinguish between facet filters and advanced search filters.facet.location=Lyndon%20Baines%20Johnson%20LibraryQuery Expansionsthesaurus=true/falseTurn on the use of the system thesaurus for query term expansion.Note that term expansions are only applied to keywords specified with the “q” parameter.thesaurus=truethesaurus.terms=cat1, cat2, cat3, . . .Add all terms from the specified categories into the query. Allowed category values are: all, related, narrower, broader. thesaurus.terms=related, narrowerthesaurus.terms.term=cat1, cat2, cat3, . . ., term1, term2, term3 . . .Specifies both categories and individual terms to add for the specified query term.Allowed category values are: all, related, narrower, broader. Individual terms can be any keyword, but are typically those returned by the system thesaurus in response to a previous query.If the “term” does not exist as a keyword in the “q” parameter, an error will be returned.thesaurus.terms.ship=related, narrowerthesaurus,terms.ship=transport,steamboat,tanker,warship,yacht,anchorSaved Result Lists (only available for registered users after login.)list=listNameSpecifies the name of the list to which results are saved (if action=newList) or added (if action=addList).If action=newList and the name already exists, an error is returned.Note: Only available for registered users after login.[TBD – to preserve system resources, the maximum number of lists is limited to XXX for registered users and YYY for ‘power’ users]See section REF _Ref379616946 \r \h 5.3 for more details.list=MyList2Export ParametersSee section REF _Ref380963454 \r \h 3.6 for all export parameters and more information.ExamplesSimple search:GET query search:GET(bess or harry) and trumanBoolean query search with phrases:GET"president truman" or "harry s truman"Search over everything from a particular location:GET"Lyndon Baines Johnson Library"Find all titles with “truman”:GET for “truman”, filter by inclusive-start date between 1980 and 1990:GET(1980,1990)Search over descriptions returning just the archival description XML:GET over posters (subject-reference from the archival description contains “poster”):GET all descriptions tagged with “Kennedy Vietnam”GET"Kennedy Vietnam"&type=descriptionFind all digital objects tagged with any tag that contains “kennedy”:GET: Note that there are 2 different fields to search for tags. When an exact match is desired, use “tagsExact” and use “tagsKeywords” field otherwise.Find documents which contain the key word “truman” and facet on locations (return a histogram of location IDs in the search results) and description level:GET documents which contain the key word “truman” and highlight matches on “truman” in the title and content fields:GET documents which contain the key word “truman” and sort by inclusive start date, descending and then sub-sort on the score (descending):GET desc,score descReturn the first 10 results which contain the key word “truman”:GET the results 11-20 which contain the key word “truman”:GET the results for “ship” and “dock” and return thesaurus expansions for the words:GET dock&thesaurus=trueReturn the results for “ship” and “dock” with “ship” expanded to include “steamship” and “warship” and “dock” expanded to include braoder terms:GET dock&thesaurus.terms.ship=steamship,warship&thesaurus.terms.dock=broaderSave the first 100 results to a list called “Mary’s List”:POST's%20List?action= addToListFromSearch&q=truman&offset=0&rows=100Add results 10 to 20 to the list called “Mary’s List”:POST's%20List?action= addToListFromSearch&q=truman&offset=10&rows=10Search all children within the series with NAID = 1523922:POST ExpressionsThis section covers the operators which are available to construct query expressions in Catalog.Keyword FieldsThe following operators are available for searching all keyword fields:Query OperatorDescriptionExamplesimplied andAny time an operator is missing, it is an implied and. Both of the words or sub-expressions specified must exist in the returned results.Katyn massacre(john or jack) kennedyandReturn results that have both of the words or sub-expressions specified.Can be upper or lower case “AND”.katyn and massacre(john or jack) AND kennedyorReturn results that have either of the words or sub-expressions specified.Can be upper or lower case “OR”.kennedy or Johnson(john kennedy) OR (lyndon johnson)notReturn results which do not have the word or sub-expression specified.Can be upper or lower case “NOT”.Expressions without a positive clause are not accepted in OPA at this time.kennedy not Jacquelinejohnson NOT "lady bird"not source:web( expression )Parenthetical expressions are allowed for more carefully specifying the boolean logic desired.(john kennedy) OR (lyndon johnson)(john or jack) AND kennedy"term term term . . ."Phrases can be expressed with double-quotes. All terms must exist in the specified order before the item is returned.Note: Phrases work differently for string fields. See note below in section REF _Ref379718796 \r \h 3.3.2."lady bird johnson""world war ii"field:expressionThe “field:” operator allows the construction of complex query expressions of multiple fields.The “field” specified can be any of the fields (except those identified as “nosearch”) from section REF _Ref379621132 \r \h 3.4. The allowed “expression” is based on the field type.Note 1: Only available with the “filter” parameter. Not available for any “f.field” parameter or the “q” parameter.Note 2: See section REF _Ref379627692 \r \h 3.3.5 below about how to use field:expression for XML fields.title:kennedy and level:(collection or recordGroup or series)Tokenization of Keyword FieldsText in keyword searches are automatically split into separate terms on punctuation and white space. For example, the query:diesel-electric tank/armored-vehicleWill be searched as:diesel AND electric AND tank AND armored AND vehicleString FieldsAll operators specified above (section REF _Ref379715832 \r \h 3.3.1) are also available for string fields.Not Separated by PunctuationHowever, unlike keyword fields, string fields are only split on white-space. Punctuation will keep string fields together. For example, the query:desc-132423 OR person-24239Will be queried exactly as specified, as two terms (not 4) separated by “or”.Strings with Embedded White SpaceSome string fields may have embedded white space. In order to search on these fields, enclose the value in double-quotes:location:"Center for Legislative Archives"Date and Date-Time FieldsThe following operators and options can be used to search over both date and date-time fields:Query OperatorDescriptionExamplesYYYYAutomatically search on the entire range specified by the year.This includes all seconds from midnight January 1 to 11:59:59 on December 31, inclusive.recordCreatedDateTime:2014releaseDate:1985YYYY-MMAutomatically search on the entire range specified by the year and month.This includes all seconds from midnight on the first of the month to 11:59:59pm on the last day of the month, inclusive.recordCreatedDateTime:2014-04releaseDate:2001-09YYYY-MM-DDAutomatically search on the entire range specified by the day, from 0:00:00 to 23:59:59.recordCreatedDateTime:2014-04-01releaseDate:2001-09-11YYYY-MM-DDTHHFor date-time fields only, automatically search on the entire range specified by the hour.recordCreatedDateTime:2014-04-01T10YYYY-MM-DDTHH:MMFor date-time fields only, automatically search on all seconds within the specified minute.recordCreatedDateTime:2014-04-01T10:30YYYY-MM-DDTHH:MM:SSFor date-time fields only, search just for the specified second.recordCreatedDateTime:2014-04-01T10:30:45range(date1,date2)For both date and date-time fields, specify the range of values (inclusive) over which to search.If any date value is truncated to just the Year or Year-month, the range will be expanded appropriately to cover the entire inclusive range.For example, for range(2001, 2002) the search will include all days from January 1, 2001 to December 31, 2002, inclusive.For range(2001-09, 2001-12), the search will include all days from the September 1, 2001 to December 31, 2001.recordCreatedDateTime:range(2014-01-01, 2014-04-30)releaseDate:range(2001, 2002)releaseDate:range(2001-09, 2001-12)range(dateTime1,dateTime2)For date-time fields only, search over the specified range, inclusive.If any date value is truncated to just the Year or Year-month, the range will be expanded appropriately to cover the entire inclusive range.For example, for range(2001, 2002) the search will include all days from January 1, 2001 to December 31, 2002, inclusive.For range(2001-09, 2001-12), the search will include all days from the September 1, 2001 to December 31, 2001.recordCreatedDateTime:range(2014-04-01T05:00:00, 2014-04-01T06:59:59)recordCreatedDateTime:range(2014-04-01T05:30, 2014-04-01T05:59)Integer FieldsNote that NAID and other identifiers are indexed as string fields by Catalog and not integer fields. (see section REF _Ref379718796 \r \h 3.3.2 for more information).Integer fields can be searched either for a specific number, or for a range.Query OperatorDescriptionExamples#Search for the number specified.fileSize:1024range(#,#)Search for all numbers within the specified range (inclusive).fileSize:range(0,1048575)XML FieldsThe XML fields specified in section REF _Ref379836854 \r \h 3.4.8 support methods for searching within the XML structure contained within those fields. This allows complex filtering of search results based on XML tag structure values.Note: These searches are slower and use up more resources than searches on standard fields. Therefore standard fields should be used whenever possible.Due to technical limitations, integer and date range searches are not allowed inside XML fields. Only standard fields support integer and date range searches. This limitation may be lifted in a future Catalog release.Query OperatorDescriptionExamplesxmlField:(expression...)Search on keywords within an XML field.This search will find the key word inside any tag within the XML data.description:posterxmlField.tag:(expression…)Search on keywords within a specific XML tag.Note 1: Any tag at any level of nesting can be specified.Note 2: The entire expression specified by (expression…) must match within the same tag. Search results will not be returned if parts of the expression match in one instance of the tag, and other parts of the expression match elsewhere.Note 3: The nested expression can contain the following operators: “and”, “or”, phrases, parenthesis, and nested field: operators for XML tags nested within the parent tag specified.Note that the NOT operator is not supported in XML fields. [TBD – restriction may be lifted in a future release]description.creator-display:(emergency and management)xmlField.tag.tag:(expression…)Specify multiple tags to require nesting.For example, withdescription.referenceunit.name:(park)only results with the keyword “park” inside the <name> tag inside the <reference-unit> tag will be returned.description.referenceunit.name:(college park)xmlField.tag.@attribute:(terms…) Attributes can be specified using the “@” symbol for the XML tag.description.subject-reference.@subject-id:4173619Example of Nested Field: OperatorsXML fields support complex nested field: operators. For example, to search only those variant control numbers where the specified variant type is “Search Identifier”, you might use the following expression:f.description.variant-control-number=(variant-type:"Search Identifier" AND variant-number:(learning center))This expression will match only descriptions which contain the specified <variant-type> and <variant-number> inside the same <variant-control-number> tag. If the type and number are within two different <variant-control-number> tags, then it will not be matched.For example, given the above search expression, the following will be matched: <variant-control-number mlr="false" num="3"> <variant-number>si Learning Center</variant-number> <variant-number-desc>si Learning Center</variant-number-desc> <variant-type>Search Identifier</variant-type> </variant-control-number>But the following will not: <variant-control-number mlr="false" num="3"> <variant-number>si Learning Center</variant-number> <variant-number-desc>si Learning Center</variant-number-desc> <variant-type>Learning Center Type</variant-type> </variant-control-number> <variant-control-number mlr="false" num="4"> <variant-number>si National History Standard Era 8</variant-number> <variant-number-desc>si National History Standard Era 8</variant-number-desc> <variant-type>Search Identifier</variant-type> </variant-control-number>Fields This section lists fields available for search, and what functions are available for each field. The “non-XML” fields are indexed for performance and to allow certain features (such as faceting, sorting, etc.) not available with XML fields.For more complex search use cases, you may need to use the “XML Fields” (see section REF _Ref379836854 \r \h 3.4.8 below), which provide search over all fields in the archival description XML, authority record XML, technical metadata XML, or content XML.Field CodesEach field is coded to identify what sorts of functions that field supports:keyword – A keyword search field.Individual keywords (separated by punctuation or spaces) can be searched within the field.See section REF _Ref379627181 \r \h 3.3.1 for search expressions that this field supports.string – A string search field.For these fields, only the entire field can be searched, and not individual words within the field. Usually used for identifiers, types, and for exact-tag searching.See section REF _Ref379718796 \r \h 3.3.2 for search expressions that this field supports.date – A date search field.Supports date range and date search expressions from section REF _Ref379627376 \r \h 3.3.3.date-time – A date-time search field.Supports time-based search expressions from section REF _Ref379627376 \r \h 3.3.3.int – An integer field.Supports integer range and integer search expressions from section REF _Ref379621672 \r \h 3.3.4.xml – The field contains embedded XML data.These fields support the parameters and search expressions specified in section REF _Ref379627692 \r \h 3.3.5.sortable – The field can be used with the “sort” parameter.no-search – The field cannot be searched. It is only used to provide information in the search results.multi-valued – The field can have multiple values. Often used for type or category-type fields where an index entry can be any of a number of different things.All other fields are single-valued.no-results – The field can only be used for search. The content of the field cannot be returned with the search results.All other fields return can return their content in the search results.facet – The field can be used for the “facet” parameter.IdentifiersThe Catalog system will track the following identifiers:naId – [string, sortable] The “NARA ID”, this is the integer identifier for all archival descriptions.NAID is managed by DAS and tagged on all DAS descriptions.Formerly known as the “ARC-ID”.See section REF _Ref382140124 \r \h 1.4.1 for more details.personId – [string, sortable] The ID for the person authority record. This is the integer identifier that spans all person records. ((NEW))The person ID is managed by DAS and tagged on all DAS Id – [string, sortable] The ID for the organization authority record. This is the integer identifier that spans all organization records. ((NEW))The organization ID is managed by DAS and tagged on all DAS descriptions.opaId – [string, sortable] This is the identifier for all entries in the search engine index.A unique OPA_ID will be assigned to everything indexed into the search engine. For example: desc-5132492, person-1432, org-1342234This ID must be unique across all archival descriptions, and authority records.See section REF _Ref380704093 \r \h 1.4.2 for more details.hmsEntryNumbers – [keyword, multi-valued] The “Holdings Management System” entry numbers for the record, a method for locating the physical materials from Archives II. Not available for all records.hmsEntryNumberSort – [string, sortable] A sort-able version of the HMS Entry Number.TBD: This will likely be a list of all HMS numbers assigned to the item, sorted and concatenated together into a primary / secondary sortable representations.localId – [string, sortable] The identifier that a NARA custodial unit specifies to be used to request archival materials in the unit's custody. Not available for all records.containerId – [string] The identifier or number for the individual container storing each specific media type.url – [keyword] Specifies the URL in the Catalog user interface where the item can be viewed. This will be different depending on the type of item:Archival descriptions – The content detail page for the description.For example: records – The content detail page for the authority record.For example: objects – The content detail page for the description with ?object=N to specify which object should be displayed.For example: pages – The URL to the web page.For example: – [no-search] Specifies a relative path to directly access this item from Catalog.Prefix this path with “” to provide the full path to the item.For archival descriptions, this will be: holdings/<NAID>For example: holdings/7229423For authority records: For people: authorities/people/<authorityId>For example: authorities/people/142345For organizations:For example: authorities/organizations/9328For digital objects: The access path to the content itself.For example: holdings/7229423/content/hst-ppp_93-1_18-02.jpgTypesThis section specifies various fields used for determining document types.source – [string, facet] The scope to which this index entry belongs. Can be one of:authorities – For all authority records.holdings – For all archival descriptions.web – For all web pages.type – [string, facet] Identifies type of result to return. Can be one of:description – For all archival descriptions.object – For all digital objects.person – For all people authority anization – For all organization authority records.archivesWeb – For all web pages from .presidentialWeb – For all web pages from presidential libraries.oldScope – [string, facet] Specifies the scope of the item according to the old OPA Pilot system.Can be any of: , descriptions, online, authority, presidentiallevel – [string, facet] The level of archival description.Only available if source = holdings.Can be any of the following: recordGroup, collection, series, fileUnit, item, object.parentLevel – [string] The level of description for the parent of this index entry in the archival hierarchy. For objects, this will be the parent of the description to which they belong.Can be any of the following: recordGroup, collection, series, fileUnit, item.iconType – [string] Specifies a type for displaying the correct icon for this index entry. This will be specified in “mime type” format.Digital objects will use the official IANA mime type for the record, normalized. See for the official list.Examples include: application/pdf, application/vnd.ms-powerpoint, audio/mp3, video/mpeg, etc.Some mime types will be normalized to a simpler type.For example, there are many different PowerPoint types. All will be normalized to “application/vnd.ms-powerpoint”.This is done to simplify the display of the appropriate icon representing the type of digital object.Custom NARA types will use mime types which start with “nara/”, for example:nara/record-group, nara/collection, nara/series, nara/item, nara/fileunit, nara/person, nara/organizationCatalog has icons for all types specified by “iconType”. Use the following path to get the image: example, if the icon type is “collection”, the image for it can be accessed using: fileFormat – [string, facet, multi-valued] Specifies the file format for the content represented by or contained within the index-entry.For digital objects, this will be the normalized mime type for the object.For descriptions, this will be a list of the unique iconType’s for all of the digital objects contained within the description.Note that mime types stored in “fileFormat” will be normalized. For example, there are many different PowerPoint types. All will be normalized to “application/vnd.ms-powerpoint” to simplify the presentation to the user.originalMimeType – [keyword] For digital objects and web pages, this will be the original mime type of the file. This field will be missing for all other index entries.tabType – [string, multi-valued] Specifies what tabs the Catalog index entry will show up on. Values can be one or more of the following: all – For everything which can show up on the “All” tab.All descriptions (with or without on-line content) and authority records.All digital objects as separately retrievable items (these will be grouped into the description to which they belong).online – Archival descriptions which contain on-line content, and web pages.All digital objects as separately retrievable items, grouped into the description to which they belong.web – Only web pages.document – Descriptions which contain on-line content where “materialsType” (see below) is “text”.image – Descriptions which contain on-line content where “materialsType” (see below) is “photographsAndGraphics”.video – Descriptions which contain on-line content where “materialsType” (see below) is “movingImages”.materialsType – [string, facet, multi-valued] The type of materials for descriptions. From from the “general-records-type” field of the archival description.drawings – “Architectural and Engineering Drawings”artifacts – “Artifacts”dataFiles – “Data Files”mapsAndCharts – “Maps and Charts”movingImages – “Moving Images”photographsAndGraphics – “Photographs and other Graphic Materials”sound – “Sound Recordings”text – “Textual Records”web – “Web Pages”Display FieldsThese are standard fields for display.title – [keyword] Holds the title to be displayed to the user for the index entry.titleSort – [no-search, sortable] Holds a sort-able version of the title.This version of the title will have leading articles (“a”, “an”, “the”, etc.) and prepositions (“of”, “by”, “in”, etc.) removed.This field may also be truncated, for very long titles.parentTitle – [keyword] Holds the title of the parent archival description to this record. For objects, this will be the parent of the description to which they belong.Will be missing for record groups and collections.Not applicable for the authorities and web sources.allTitles – [keyword, multi-valued] Holds all available titles for the index-entry, including subtitle, series-title, other-titles, and series-sub-titles.webArea – [keyword] Holds the area of the web site to which a web page belongs.This is displayed to users to give them an idea of where within the web site the search result is from. For presidential libraries, this will be the title of the presidential library web site.webAreaUrl – [keyword] Holds the URL which corresponds to the webArea field.For example, if the webArea is “: Press Releases” the webAreaUrl will be “”.For presidential libraries, this will be the home page for the library.content – [keyword] This is the main content field used for generating dynamic teasers.Note that, while all of the content is indexed for keyword search, only the first [TBD – How much?] 100K bytes of the content will be stored to generate dynamic teasers.creators – [keyword, multi-valued] Holds a list of creators of the content from the archival description.teaser – [keyword] A representative summary of the document, typically the first 500 characters of the content.This field should be displayed for any document which doesn’t otherwise have highlighted content to show.isOnline – [boolean] Specifies if the index entry represents something which is on-line.This will be true for all digital objects and any archival description which contains a digital object.hasOnline – [boolean] specifies if the index entry represents a hierarchical archival description which has within it on-line content.This will be true for any archival description which has a descendent description that contains digital objects.For example, for a series which contains an item that has digital objects, the series will be flagged as “hasOnline” of “true”.thumbnailFile – [no-search] Holds the filename of the thumbnail for the item within the package to which this item belongs.The full URL of the thumbnail can be constructed with the following formula: not present, the iconType (see above) should be used to display the appropriate icon for the document.titleDate – [no-search] This is fully formatted date string for the item. Can be a date range such as “1892 – 1972”.More Facet FieldsOther fields for faceting include level, fileFormat, and materialsType. See the sections above for more information on those fields.location – [string, multi-valued, facet] Holds the physical location of the archival materials represented by this index-entry.This information comes from the <reference-units> section of the archival description. Only the primary name of the location is stored.Note that copies of the content may be available from multiple locations. Therefore, this field is multi-valued.This field can be used for doing exact searches only on a location. For keyword searches on a location name, use the field below.locationKeywords – [keyword, multi-valued, no-results] Used to search for keywords within the physical locations.Note: Use “location” to return the location data in the search results.locationIds – [string, facet, multi-valued] Holds the reference IDs of the physical location of the archival materials represented by this index-entry.Location Ids will be used by standard interfaces for location facets.See the appendix (section REF _Ref380879256 \r \h 6.1) for a list of location IDs.dateRangeFacet – [string, facet, multi-valued] Holds a list of the date ranges (e.g. 1600-1699, 1700-1749, 1750-1799, 1800-1809, 1810-1819, etc.) appropriate for this index entry.Archival Hierarchy FieldsAlso see section REF _Ref382140495 \r \h 3.4.3 for parentTitle and section REF _Ref379734256 \r \h 3.4.2 for parentLevel.parentNaId – [string] The NAID of the parent of this item in the archival descriptions hierarchy. For objects, this will be the parent of the description to which they belong.Note that this field will have the single token “root” for record groups and collections.Use this field to search for all directl children for any archival description.ancestorNaIds – [string, multi-valued] Holds a space-separated list of all ancestor NAIDs in the archival descriptions hierarchy for this Catalog index entry.Use this field to search for any descendent for any archival description.hasChildren – [boolean] “true” if this record is an archival description with child archival descriptions. “false” otherwise.Digital Object InformationThis section contains fields specifically for digital objects. These fields will be missing for other types of records. See also originalMimeType above for the mime type of the digital object.objectId – [string] A unique identifier for the digital object.Note: This will be the DAS stable object ID for the digital object, or a unique (and stable) object ID within the SEIP, as appropriate.objectSortNum – [int, sortable] For all digital objects, this is the object number used to sort the object amongst its peers.Note that images will be sorted first (as they are displayed in Catalog), followed by other documents.objectFile – [string] The file name of the object.fileSize – [int] The file size of the digital object, in bytes.AnnotationsThis section covers annotations which can be attached to digital objects, archival descriptions, and authority records. These fields are separated from the “objects” field (see section REF _Ref379836854 \r \h 3.4.8) to allow for date range searching, facets on tags, and faster searching for contributors.In the text below, index entry refers to any archival description or authority record (for comments and tags) or digital object (for any sort of annotation).allContributors – [string, multi-valued] – A list of the user IDs for everyone who has contributed in any way to this index entry.allContributionsFirstDateTime – [date-time] The date-time when the first contribution (of any type) was made to this index entry.allContributionsLatestDateTime – [date-time] The date-time when the most recent contribution (of any type) was created or modified.TagstagsKeywords – [keyword, multi-valued, no-result] Holds a list of all tags indexed as keywords for flexible searching.Use tagsExact to see the exact values of the tags placed on a Catalog index entry.tagsExact – [string, multi-valued,facet] Holds a list of all tags indexed as strings, so exact tags can be matched.tagsContributors – [string, multi-valued] Holds a list of all contributors (by registered user ID) who have contributed tags to this index entry. Multiple tags contributed by a single contributor will be shown only once.tagFirstDateTime – [date-time] Holds the date-time when the first tag was placed on this index entry.tagLatestDateTime – [date-time] Holds the date-time of the most recent tag to be placed on this index mentscommentFirstDateTime – [date-time] Holds the date-time when the first comment was placed on this index mentLatestDateTime – [date-time] Holds the date-time of the most comment or reply to be added to this index mentsContributors – [string, multi-valued] Holds a list of all contributors (by registered user ID) who have contributed comments or replies to this index entry. Multiple comments or replies contributed by a single contributor will be shown only once.TranscriptionstranscriptionFirstDateTime – [date-time] Holds the date-time when the transcription was first created.transcriptionLatestDateTime – [date-time] Holds the date-time of the most recent edit to this transcription.transcriptionContributors – [string, multi-valued] Holds the list of everyone who has contributed to this transcription.TranslationstranslationFirstDateTime – [date-time] Holds the date-time when the first translation was added to this index entry.translationLatestDateTime – [date-time] Holds the date-time of the most recent edit to any translation on this index entry occurred.translationContributors – [string, multi-valued] Holds the list of everyone who has contributed any translation to this index entry.XML FieldsThis section covers XML fields available from Catalog. XML fields contain full XML content which can be searched using XML tags and attributes as described above in section REF _Ref379627692 \r \h 3.3.5.Note that XML fields will be automatically converted to JSON if JSON results are requested.description – [xml] Contains the XML for the archival description.Only available for archival descriptions and digital objects(i.e., type=description or object).For digital objects, this will hold the xml of the archival description to which the object belongs.For purposes of scalability, and since digital objects can be independently retrieved, digital object information (the <objects> tag and its contents) is not included with this XML.TBD: Currently this is the <archival-description> XML (the old ARC export format). Should this be updated?TBD: Need reference where the user can find a full description of this XML format.authority – [xml] Contains the complete XML for the authority record.Only available for authority records (i.e., source=authority).TBD: Currently this is the <person> and <organization> XML (the old ARC export format). Should this be updated?TBD: Need reference where the user can find a full description of this XML format.objects – [xml] Holds the complete object XML for all digital objects (if a description) OR just the one <object> tag (for digital objects).Note: The content of objects will be as shown in section REF _Ref381136677 \r \h 2.3.1.2 with “annotations=full”. This means that the full content of all annotations (including all transcriptions and translations) will be copied into this XML field.Authority InformationThis section holds authority identifiers used to locate descriptions which reference a particular authority record.Note: The following fields are only tagged on archival descriptions and digital objects. All of these fields will be missing for all other types of Catalog index entries.TBD: Are the different types of authority relationships (creator, donor, etc.) still valid? The following values do not match up exactly to the LCDRG.All authority IDs in the fields below will be specified as OPA ID’s for the authority record, either: person<number> or org-<number>, as appropriate. For example, “person-3825288”.allAuthorityIds – [string, multi-valued] holds a list of all authority IDs linked to this archival description.This field is used to limit the search results to only descriptions which contain any link to the specified authority record.creatorIds – [string, multi-valued] holds the authority IDs for all authorities tagged as “creator” for the content described by the archival description.subjectIds – [string, multi-valued] holds the authority IDs for all authorities tagged as a “subject” for the content described by the archival description.donorIds – [string, multi-valued] holds the authority IDs for all authorities tagged as a “donor” for the content described by the archival description.contributorIds – [string, multi-valued] holds the authority IDs for all authorities tagged as a “contributor” for the content described by the archival description.personalReferenceIds – [string, multi-valued] holds the authority IDs for all authorities tagged as a “personal reference” for the content described by the archival description.Dates and TimesThis section specifies date and date-time fields which can be used for search and sorting within Catalog. See also “titleDate” above in section REF _Ref382140771 \r \h 3.4.3.TBD: Are these the appropriate dates and date-times to be included in the index? Need more information from NARA.recordCreatedDateTime – [date-time, sortable] The date/time the record was created.This is the time that the catalog record was created in NARA (not the creation date of the original content).recordUpdatedDateTime – [date-time, sortable] The date/time the record was last updated.This is the time that the catalog record was updated by NARA (not the last update date of the original content).firstIngestedDateTime – [date-time, sortable] The date/time the index-entry was first ingested into Catalog.This date/time is useful for locating items which are “new to Catalog”, for example as an RSS feed of “what’s new”.Note: This date may reset when a new version of Catalog is released.ingestedDateTime – [date-time, sortable] The date/time the index-entry was ingested into Catalog.This date/time is updated whenever the index-entry is re-loaded or re-processed into Catalog.productionDate – [date, sortable] The date on which an item was produced or created.productionDateQualifier - [no-search] Qualifier for productionDate (section REF _Ref379697882 \r \h 3.4.10.1).broadcastDate – [date, sortable] The date on which the item was first broadcast or another known broadcast date, if the first date is unknown.broadcastDateQualifier - [no-search] Qualifier for broadcastDate (section REF _Ref379697882 \r \h 3.4.10.1).releaseDate – [date, sortable] The date on which the audiovisual item was released for distribution.releaseDateQualifier - [no-search] Qualifier for releaseDate (section REF _Ref379697882 \r \h 3.4.10.1).coverageStartDate – [date, sortable] The starting date of the time period covered by the subject(s) of the record group, collection, or archival materials.coverageStartDateQualifier - [no-search] Qualifier for coverageStartDate (section REF _Ref379697882 \r \h 3.4.10.1).coverageEndDate – [date, sortable] The ending date of the time period covered by the subject(s) of the record group, collection, or archival materials.coverageEndDateQualifier - [no-search] Qualifier for coverageEndDate (section REF _Ref379697882 \r \h 3.4.10.1).inclusiveStartDate – [date, sortable] The beginning date on which the record group, collection, or series was created, maintained, or accumulated by the creator. Serves as a primary access point to allow users to retrieve or sort by time period.inclusiveStartDateQualifier - [no-search] Qualifier for inclusiveStartDate (section REF _Ref379697882 \r \h 3.4.10.1).inclusiveEndDate – [date, sortable] The last date on which the record group, collection, or series was created, maintained, or accumulated by the creator.inclusiveEndDateQualifier - [no-search] Qualifier for inclusiveEndDate (section REF _Ref379697882 \r \h 3.4.10.1).authorityStartDate – [date, sortable] The starting date for the person or organization.For people, this will be the birth date.For organizations, this will be the date the organization was established.authorityStartDateQualifier - [no-search] Qualifier for authorityStartDate (section REF _Ref379697882 \r \h 3.4.10.1).authorityEndDate – [date, sortable] The ending date for the person or organization.For people, this will be the death date.For organizations, this will be the date the organization was abolished.Will be missing if the authority still exists.authorityEndDateQualifier - [no-search] Qualifier for inclusiveStartDate (section REF _Ref379697882 \r \h 3.4.10.1).Date Qualifiers in CatalogDue to technical reasons, dates in Catalog must be stored as full dates (YYYY-MM-DD). Partial dates (such as YYYY) are not allowed in date fields. Therefore, every date field which may be indeterminate has a “dateQualifier” field which identifies how to qualify the date in the date field.In Catalog, dateQualifier fields can have the following values:Y – Year only, value is knownY? – Year only, value is uncertainYca – Year only, date is approximate (e.g., “circa”)YM – Year and month, value is knownYM? – Year and month, value is uncertainYMca – Year and month, date is approximate (e.g., “circa”)YMD – Full date: year, month and day, value is knownYMD? – Full date: year, month and day, value is uncertainYMDca – Full date: year, month and day, date is approximate (e.g., “circa”)For example: if productionDate = “1948-01-01” and productionDateQualifier is “Yca”, then the date should be displayed as “ca. 1948”.Search Results OutputIn response to a search request, the search API will return the following information, either structured as XML or JSON as requested:Header informationStatus of the requestAny error messages which occurredThe time it took to satisfy the requestAll of the search parameters specified with the requestSearch resultsThe main list of search results, including the total number of documents which match the queryEach result will contain the score (aka relevancy) of the result and a list of all of the fields requested to be included with the result.Grouped web page resultsIf group=web is specified, then web site results will be returned as a separate section.Facet valuesIf facet=true, all facet fields and facet results are returned.HighlightsIf highlight=true, then specified highlighted fields are returned.Thesaurus expansionsIf thesaurus=true, then thesaurus expansion for each keyword are returned.Each of these sections is discussed individually. Some complete examples are found at the end of this section.Header InformationThe standard headers specified in section REF _Ref379726032 \r \h 1.5.2 are returned by the search API. For example:XML ExampleGET status="200" time="231"><request path="/iapi/v1"><action>search</action><q>truman</q></request></header> . . search results will be returned here .</opa-response>JSON ExampleGET{ "header":{ "@status":"200", "@time":"231", "request":{ "@path":"/iapi/v1", "action":"search" "q":"truman" } }, . . search results will be returned here .}Search API Error CodesThe following error codes are currently defined as part of the Search API response:Error CodeDescriptionParametersEMBEDDED_HTMLThe query or filter parameters contain embedded HTML which implies a potential cross-site scripting attack.param: The parameter where the embedded HTML was detected.INVALID_PARAM_VALUEThe value specified to a parameter was invalid. For example, an incorrect source value, incorrect group type, etc.param: The parameter which contained the invalid value.INVALID_FIELDA request was made to search over an invalid field.param: The parameter which contained the invalid field.field: The invalid field name.QUERY_PARSE_ERRORAn error occurred parsing the query.Note: This should rarely occur. Default behavior is defined for most invalid expressions.param: The parameter which contained the invalid search expression.OFFSET_LIMIT_EXCEEDEDThe maximum search result request has exceeded the limit. See the “offset” parameter for more details.request: The result number requested.max: The maximum result number allowed.ROWS_LIMIT_EXCEEDEDThe maximum number of rows to be returned with the search results was reached.request: The number of rows requested.max: The maximum number of rows allowed.INVALID_LISTAn invalid list name was specified when saving results to a list.This typically occurs when using the “action=addList” parameter.list: The list name requested.LIST_LIMIT_EXCEEDEDThe maximum number of lists that a single user can create was exceeded.list: The name for the new list requested.LIST_SIZE_EXCEEDEDThe maximum number of results which can be added to a list was exceeded.request: The number of results requested to be added to the list.max: The maximum number of results allowed.QUERY_TIMEOUTQuery execution took too long and was canceled.max: The maximum number of seconds allowed for a query to execute.XML ExampleGET status="400" time="8"><request path="/iapi/v1"><action>search</action><q>truman</q><rows>10000</rows></request></header> <errors> <error code="ROW_LIMIT_EXCEEDED"><request>10000</request><max>200</max> </error> </errors> . . search results will be returned here .</opa-response>JSON ExampleGET{ "header":{ "@status":"400", "@time":"8", "request":{ "@path":"/iapi/v1", "action":"search", "q":"truman", "rows":"10000" } }, "errors":{ "error":{ "@code":"ROW_LIMIT_EXCEEDED", "request":"10000", "max":"200" } }, . . search results will be returned here .}Search ResultsThe following is a general outline of the search results section:<results total="--total-matching-results --" offset="--first-result-num--" rows="-- num-results--"> <result num="--result-number--" score="--relevancy-score--"> <FIELD-NAME1>FIELD-VALUE1</FIELD-NAME1> <FIELD-NAME2>FIELD-VALUE2</FIELD-NAME2> <FIELD-NAME3>FIELD-VALUE3</FIELD-NAME3> . . MORE FIELDS GO HERE . </result> . . MORE RESULTS GO HERE .</results>In the above outline, the various values are:total-matching-results – The total number of results across all of Catalog which match the query. This number may be thousands or millions large.first-result-num – The offset number of the first result returned.rows – The actual number of results returned.result-number – The result number (where 0 is the first result) within the list of all possible results (not just results returned by this query).relevancy-score – The relevancy score returned by the search engine.The number doesn’t actually mean anything. It is only useful for sorting results by relevancy.XML ExampleGET total="6695" offset="0" rows="25"> <result num="0" score="2.34"> <source>holdings</source> <type>description</type> <naId>7226539</naId> <opaId>desc-7226539</opaId> <title>Letter from George McGovern to Harry S. Truman</title> <parentTitle>Subject Files, 1953 - 1972</parentTitle> <titleDate>1972-08-19</titleDate> <url>; <accessPath>holdings/7226539</accessPath> <localId>hst-ppp_93-1_18</localId> <iconType>nara/item</iconType> <creators><val>Truman, Harry S., 1884-1972</val></creators> <thumbnailFile>hst-ppp_93-1_18-01.jpg</thumbnailFile> </result> <result num="1" score="2.14"> <source>holdings</source> <type>description</type> <naId>7283002</naId> <opaId>desc-7283002</opaId> <title>Spring 1976: 7-69-1: Truman on CIA (Examining President Truman's Role in the Establishment of the Agency), by Thomas F. Troy</title> <parentTitle>Articles from "Studies in Intelligence", 1955 - 1992</parentTitle> <parentLevel>series</parentLevel> <url>; <accessPath>holdings/7283002</accessPath> <hmsEntryNumbers><val>A1 27</val></hmsEntryNumbers> <iconType>nara/fileUnit</iconType> <creators><val>Central Intelligence Agency. (12/04/1981 - )</val></creators> <thumbnailFile>263-a1-27-box-7-69-1-0001.jpg</thumbnailFile> </result> . . MORE RESULTS GO HERE .</results>JSON ExampleGET"results":{ "@total":"6695", "@offset":"0", "@rows":"25", "result":[ { "@num":"0", "@score":"2.34", "source":"holdings", "type":"description", "naId":"7226539", "opaId":"desc-7226539", "title":"Letter from George McGovern to Harry S. Truman", "parentTitle":"Subject Files, 1953 - 1972", "titleDate":"1972-08-19", "url":"", "accessPath":"holdings/7226539", "localId":"hst-ppp_93-1_18", "iconType":"nara/item", "creators":{ "val":"Truman, Harry S., 1884-1972" }, "thumbnailFile":"hst-ppp_93-1_18-01.jpg" }, { "@num":"1", "@score":"2.14", "source":"holdings", "type":"description", "naId":"7283002", "opaId":"desc-7283002", "title":"Spring 1976: 7-69-1: Truman on CIA (Examining President Truman's Role in the Establishment of the Agency), by Thomas F. Troy", "parentTitle":"Articles from \"Studies in Intelligence\", 1955 - 1992", "parentLevel":"series", "url":"", "accessPath":"holdings/7283002", "hmsEntryNumbers":{ "val":"A1 27" }, "iconType":"nara/fileUnit", "creators":{ "val":"Central Intelligence Agency. (12/04/1981 - )" }, "thumbnailFile":"263-a1-27-box-7-69-1-0001.jpg" } . . MORE RESULTS GO HERE . ],}Optimized Results“Optimized Results” are results which have been chosen by NARA as the best results for specified queries. When that query is entered, the optimized results will be “elevated” to the top of the results set. These are often called “best bets” or “featured results” in other systems.When a result is one of the “optimized results” chosen by NARA, then it will have the@optimized attribute attached to it: <result num="0" score="2.34" optimized="true"> . . . </result>TBD: Can we change this attribute to “featured” and change all of the text to say “featured Results”? It would be more recognizable in the industry.Search results with XML FieldsWhen search results contain XML fields (see section REF _Ref379836854 \r \h 3.4.8), the XML data will be included inside the top-level field.For example, when returning the “description” field, the entire <archival-description> XML will be provided in the search results:XML ExampleGET total="6695" offset="0" rows="25"> <result num="0" score="2.34"> <source>holdings</source> <type>description</type> <naId>7226539</naId> <opaId>desc-7226539</opaId> <title>Letter from George McGovern to Harry S. Truman</title> <description> <arc-id>7226539</arc-id> <arc-id-desc>7226539</arc-id-desc> <title>Letter from George McGovern to Harry S. Truman</title> <title-only>Letter from George McGovern to Harry S. Truman</title-only> <local-identifier>hst-ppp_93-1_18</local-identifier> <local-identifier-desc>hst-ppp_93-1_18</local-identifier-desc> <created-timestamp>9/21/2013 14:39:46</created-timestamp> <level-of-desc level-id="NAVI"> <lod-display>Item</lod-display> </level-of-desc> . . More description fields go here . </description> </result> . . MORE RESULTS GO HERE .</results>JSON ExampleGET"results":{ "@total":"6695", "@offset":"0", "@rows":"25", "result":{ "@num":"0", "@score":"2.34", "source":"holdings", "type":"description", "naId":"7226539", "opaId":"desc-7226539", "title":"Letter from George McGovern to Harry S. Truman", "parentTitle":"Subject Files, 1953 - 1972", "titleDate":"1972-08-19", "url":"", "accessPath":"holdings/7226539", "localId":"hst-ppp_93-1_18", "iconType":"nara/item", "creators":{ "val":"Truman, Harry S., 1884-1972" }, "thumbnailFile":"hst-ppp_93-1_18-01.jpg", "description":{ "arc-id":"7226539", "arc-id-desc":"7226539", "title":"Letter from George McGovern to Harry S. Truman", "title-only":"Letter from George McGovern to Harry S. Truman", "local-identifier":"hst-ppp_93-1_18", "local-identifier-desc":"hst-ppp_93-1_18", "created-timestamp":"9/21/2013 14:39:46", "level-of-desc":{ "@level-id":"NAVI", "lod-display":"Item" }, . . More description fields go here . } }, . . MORE RESULTS GO HERE .}Search results with portions of XML FieldsIn addition to selecting an entire XML field, portions of the XML field can be selected:XML ExampleGET total="6695" offset="0" rows="25"> <result num="0" score="2.34"> <source>holdings</source> <type>description</type> <naId>7226539</naId> <opaId>desc-7226539</opaId> <title>Letter from George McGovern to Harry S. Truman</title> <parentTitle>Subject Files, 1953 - 1972</parentTitle> <titleDate>1972-08-19</titleDate> <url>; <accessPath>holdings/7226539</accessPath> <localId>hst-ppp_93-1_18</localId> <iconType>nara/item</iconType> <creators><val>Truman, Harry S., 1884-1972</val></creators> <thumbnailFile>hst-ppp_93-1_18-01.jpg</thumbnailFile> <description> <local-identifier>hst-ppp_93-1_18</local-identifier> <subject-references> <subject-reference num="1" standard="Y" subject-id="1300242" subject-type="PER"> <display-name>Dewey, Thomas E. (Thomas Edmund), 1902-1971</display-name> </subject-reference> <subject-reference num="2" standard="Y" subject-id="3868518" subject-type="SUBJ"> <display-name>Presidential campaign, 1972</display-name> </subject-reference> <subject-reference num="3" standard="Y" subject-id="2396882" subject-type="PER"> <display-name>Shriver, Sargent, 1915-2011</display-name> </subject-reference> </subject-references> </description> </result> . . MORE RESULTS GO HERE .</results>JSON ExampleGET"results":{ "@total":"6695", "@offset":"0", "@rows":"25", "result":[ { "@num":"0", "@score":"2.34", "source":"holdings", "type":"description", "naId":"7226539", "opaId":"desc-7226539", "title":"Letter from George McGovern to Harry S. Truman", "parentTitle":"Subject Files, 1953 - 1972", "titleDate":"1972-08-19", "url":"", "accessPath":"holdings/7226539", "localId":"hst-ppp_93-1_18", "iconType":"nara/item", "creators":{ "val":"Truman, Harry S., 1884-1972" }, "thumbnailFile":"hst-ppp_93-1_18-01.jpg", "description":{ "local-identifier":"hst-ppp_93-1_18", "subject-references":{ "subject-reference":[ { "@num":"1", "@standard":"Y", "@subject-id":"1300242", "@subject-type":"PER", "display-name":"Dewey, Thomas E. (Thomas Edmund), 1902-1971" }, { "@num":"2", "@standard":"Y", "@subject-id":"3868518", "@subject-type":"SUBJ", "display-name":"Presidential campaign, 1972" }, { "@num":"3", "@standard":"Y", "@subject-id":"2396882", "@subject-type":"PER", "display-name":"Shriver, Sargent, 1915-2011" } ] } } }, . . MORE RESULTS GO HERE . ]}Archival descriptions with digital objectsYou can search over both archival descriptions with specified digital objects, but return only a list of archival descriptions.XML ExampleGET total="6695" offset="0" rows="25"> <result num="0" score="2.34"> <source>holdings</source> <type>description</type> <naId>7226539</naId> <opaId>desc-7226539</opaId> <title>Letter from George McGovern to Harry S. Truman</title> <objects> <object> <file path="./content/hst-ppp_93-1_18-01.jpg"/> <thumbnail path="./opa-rendition/thumbnails/hst-ppp_93-1_18-01-thumb.jpg" mime="image/jpeg"/> <annotations> <transcription lastModified="2014-02-21T16:22:58" isauthoritative="false" version="232"> <users total="3"> <user id="tjefferson" fullName="Thomas Jefferson" isNaraStaff="true" lastModified="2014-02-21T16:22:58" /> <user id="mstewart" fullName="Meredith Stewart" isNaraStaff="true" lastModified="2014-02-08T12:59:49"/> <user id="kmartin" lastModified="2014-02-02T08:44:12" /> </users> <text>GEORGE McGOVERN United States Senate Washington, D.C. 20510 August 19, 1972 The Honorable Harry S. Truman Independence, Missouri My dear Mr. President: It is an honor for me, as our party's candidate for President of the United States. . .</text> </transcription> </annotations> </object> <object> <file path="./content/hst-ppp_93-1_18-02.jpg"/> <thumbnail path="./opa-rendition/thumbnails/hst-ppp_93-1_18-02-thumb.jpg" mime="image/jpeg"/> </object> <object> <file path="./content/hst-ppp_93-1_18-03.jpg"/> <thumbnail path="./opa-rendition/thumbnails/hst-ppp_93-1_18-03-thumb.jpg" mime="image/jpeg"/> </object> </objects> </result> . . MORE RESULTS GO HERE .</results>JSON ExampleGET{ "@total":"6695", "@offset":"0", "@rows":"25", "result":[ { "@num":"0", "@score":"2.34", "source":"holdings", "type":"description", "naId":"7226539", "opaId":"desc-7226539", "title":"Letter from George McGovern to Harry S. Truman", "objects":{ "object":[ { "file":{ "@path":".\/content\/hst-ppp_93-1_18-01.jpg" }, "thumbnail":{ "@path":".\/opa-rendition\/thumbnails\/hst-ppp_93-1_18-01-thumb.jpg", "@mime":"image\/jpeg" }, "annotations":{ "transcription":{ "@lastModified":"2014-02-21T16:22:58", "@isauthoritative":"false", "@version":"232", "users":{ "@total":"3", "user":[ { "@id":"tjefferson", "@fullName":"Thomas Jefferson", "@isNaraStaff":"true", "@lastModified":"2014-02-21T16:22:58" }, { "@id":"mstewart", "@fullName":"Meredith Stewart", "@isNaraStaff":"true", "@lastModified":"2014-02-08T12:59:49" }, { "@id":"kmartin", "@lastModified":"2014-02-02T08:44:12" } ] }, "text":"GEORGE McGOVERN\n United States Senate\n Washington, D.C. 20510\n\n August 19, 1972\n\n The Honorable Harry S. Truman\n Independence, Missouri\n\n My dear Mr. President:\n\n It is an honor for me, as our party's\n candidate for President of the United States. . ." } } }, { "file":{ "@path":".\/content\/hst-ppp_93-1_18-02.jpg" }, "thumbnail":{ "@path":".\/opa-rendition\/thumbnails\/hst-ppp_93-1_18-02-thumb.jpg", "@mime":"image\/jpeg" } }, { "file":{ "@path":".\/content\/hst-ppp_93-1_18-03.jpg" }, "thumbnail":{ "@path":".\/opa-rendition\/thumbnails\/hst-ppp_93-1_18-03-thumb.jpg", "@mime":"image\/jpeg" } } ] } }, . . MORE RESULTS GO HERE . ]}Web Page ResultsWhen the group=web parameter is specified, a set of 3 web results will be returned separate from the standard results, so they can be styled as a “call out” inside the standard (aka?“organic”) results. Further, the web results will contain a fixed set of fields.To get more web results, or download additional fields with your web results, submit separate queries for web results (using the source=web parameter) and the standard results without grouping.XML ExampleGET total="312" offset="0" rows="3"> <result num="0" score="1.54"> <opaId>; <title>Harry S. Truman Library and Museum</title> <webArea>Harry S. Truman Library and Museum</webArea> <webAreaUrl>; <url>; <iconType>text/html</iconType> </result> <result num="1" score="1.55"> <opaId>; <title>Spring Prologue Magazine Highlights Truman’s 125th Birthday</title> <webArea>: Press Releases</webArea> <webAreaUrl>; <url>; <iconType>text/html</iconType> </result> <result num="2" score="1.53"> <opaId>; <title>Truman: HST Biography</title> <url>; <webArea>Harry S. Truman Library and Museum</webArea> <webAreaUrl>; <iconType>text/html</iconType> </result></webPages>JSON ExampleGET"webPages":{ "@total":"312", "@offset":"0", "@rows":"3", "result":[ { "@num":"0", "@score":"1.54", "opaId":"", "title":"Harry S. Truman Library and Museum", "webArea":"Harry S. Truman Library and Museum", "webAreaUrl":"", "url":"", "iconType":"text/html" }, { "@num":"1", "@score":"1.55", "opaId":"", "title":"Spring Prologue Magazine Highlights Truman's 125th Birthday", "webArea":": Press Releases", "webAreaUrl":"", "url":"", "iconType":"text/html" }, { "@num":"2", "@score":"1.53", "opaId":"", "title":"Truman: HST Biography", "url":"", "webArea":"Harry S. Truman Library and Museum", "webAreaUrl":"", "iconType":"text/html" } ]}Pdf Files ResultsWhen the result contain pdf documents, one more field will be added in addition to the regular fields (pageCount, CreationDate, LastModified, Title), that is the extractedText, containing the text layer of the document itself.For PDF objects, a field called extractedText will be present on the objects node.XML Example<result><num>1</num><score>0.14369197</score><type>object</type><naId>12019827</naId><objects?created="2015-04-21T05:33:05Z"?version="OPA-OBJECTS-1.0">?<object?id="15951168"?objectSortNum="1"><file?mime="application/pdf"?name="1069084.pdf"?path="content/library/document/0003/1069084.pdf"?type="primary"url=""?/><thumbnail?mime="image/jpeg"?path="opa-renditions/thumbnails/1069084.pdf-thumb.jpg"?url=""?/>?<technicalMetadata><size>1272102</size><mime>application/pdf</mime><createDate>2012-01-31T19:45:28Z</createDate><modifyDate>2012-09-17T15:09:36Z</modifyDate><Page-Count>24</Page-Count><title>American Film Institute Life Achievement Dinner, Los Angeles, California, March 9, 1976</title>?</technicalMetadata>?</object></objects>?</result>GET ExampleGET iapi/v1?action=search&rows=10&q=12019827object: {@id: "15951168"@objectSortNum: "1"file: {@mime: "application/pdf"@name: "1069084.pdf"@path: "content/library/document/0003/1069084.pdf"@type: "primary"@url: ""}-thumbnail: {@mime: "image/jpeg"@path: "opa-renditions/thumbnails/1069084.pdf-thumb.jpg"@url: ""}-technicalMetadata: {size: "1272102"mime: "application/pdf"createDate: "2012-01-31T19:45:28Z"modifyDate: "2012-09-17T15:09:36Z"Page-Count: "24"title: "American Film Institute Life Achievement Dinner, Los Angeles, California, March 9, 1976"}-Facet ValuesFacets are grouped under the <facets> tag, which contains a list of <field> tags, each with a list of facet values.Use the parameter facet=true to turn on facets. Use facet.fields to specify the list of fields for which facet values are computed. See the complete list of fields (section REF _Ref379621132 \r \h 3.4) to see what fields are eligible for being used as facets.XML ExampleGET; <field name="type"> <v name="description" count="72"/> <v name="archivesWeb" count="13"/> <v name="organization" count="8"/> <v name="person" count="4"/> <v name="presidentialWeb" count="3"/> </field> <field name="fileFormat"> <v name="application/pdf" count="50"/> <v name="application/vnd.ms-powerpoint" count="17"/> <v name="video/mpeg4" count="3"/> <v name="audio/mp3" count="1"/> <v name="image/gif" count="1"/> </field></facets>JSON ExampleGET"facets":{ "field":[ { "@name":"type", "v":[ { "@name":"description", "@count":"72" }, { "@name":"archivesWeb", "@count":"13" }, { "@name":"organization", "@count":"8" }, { "@name":"person", "@count":"4" }, { "@name":"presidentialWeb", "@count":"3" } ] }, { "@name":"fileFormat", "v":[ { "@name":"application/pdf", "@count":"50" }, { "@name":"application/vnd.ms-powerpoint", "@count":"17" }, { "@name":"video/mpeg4", "@count":"3" }, { "@name":"audio/mp3", "@count":"1" }, { "@name":"image/gif", "@count":"1" } ] }, ],}HighlightsDocument highlights are stored in a separate section and referenced to the document by OPA-ID. The <highlights> section will contain a list of <result> tags, each of which references the OPAID of the result that they are associated with.Turn on highlights with the highlight=true param. See section REF _Ref379621132 \r \h 3.4 for additional parameters to specify what fields are highlighted.Only fields which actually contain keywords that match the query are returned in the highlights section. In the example below, the second result (desc-7283002) contains no <creators> tag, because none of the creators had the keyword “truman” in the text. The highlights themselves are indicated with embedded <em> tags. Note that the angles are escaped in XML:Letter from George McGovern to Harry S. &lt;em&gt;Truman&lt;/em&gt;But not in JSON:Letter from George McGovern to Harry S. <em>Truman</em>At most 3 highlighted snippets will be created for each field. Only words specified in the “q” parameter will be highlighted in search results.XML ExampleGET; <result opaId="desc-7226539"> <title> <val>Letter from George McGovern to Harry S. &lt;em&gt;Truman&lt;/em&gt;</val> </title> <content> <val>The Honorable Harry ·s. &lt;em&gt;Truman&lt;/em&gt; Independence, Missouri My dear Mr. President:...</val> <val>GEORGE McGOVERN WASHINGTON, D.C. 20510 AIR MAIL SPECIAL DELIVERY The Honorable Harry s. &lt;em&gt;Truman&lt;/em&gt; Independence, Missouri AIR MAIL SPECIAL DELIVERY...</val> </content> <creators><val>&lt;em&gt;Truman&lt;/em&gt;, Harry S., 1884-1972</val></creators> </result> <result opaId="desc-7283002"> <title> <val>Spring 1976: 7-69-1: &lt;em&gt;Truman&lt;/em&gt; on CIA (Examining President &lt;/em&gt;Truman&lt;/em&gt;'s Role in the Establishment of the Agency), by Thomas F. Troy</val> </title> <content> <val>Examining President Truman's role in the establishment of the Agency TRUMAN ON CIA Thomas F. Troy...</val> <val>President Harry S. Truman had his own version of his role in the establishment of the Central Intelligence Agency. He once summed it up this way: '' I got a couple of...</val> <val>In Truman's most extended account, in his Memoirs, he related how he discovered the lack of coordinated intelligence in Washington, asked what was being done about it, solicited advice</val> </content> </result> . . Highlights for more results go here .</highlights>JSON ExampleGET"highlights":{ "result":[ { "@opaId":"desc-7226539", "title":[ "Letter from George McGovern to Harry S. <em>Truman</em>" ], "content":[ "The Honorable Harry s. <em>Truman</em> Independence, Missouri My dear Mr. President:...", "GEORGE McGOVERN WASHINGTON, D.C. 20510 AIR MAIL SPECIAL DELIVERY The Honorable Harry s. <em>Truman</em> Independence, Missouri AIR MAIL SPECIAL DELIVERY..." ], "creators":[ "<em>Truman</em>, Harry S., 1884-1972" ] }, { "@opaId":"desc-7283002", "title":[ "Spring 1976: 7-69-1: <em>Truman</em> on CIA (Examining President </em>Truman</em>'s Role in the Establishment of the Agency), by Thomas F. Troy" ], "content":[ "Examining President Truman's role in the establishment of the Agency TRUMAN ON CIA Thomas F. Troy...", "President Harry S. Truman had his own version of his role in the establishment of the Central Intelligence Agency. He once summed it up this way: '' I got a couple of...", "In Truman's most extended account, in his Memoirs, he related how he discovered the lack of coordinated intelligence in Washington, asked what was being done about it, solicited advice" ] }, . . Highlights for more results go here . ],}Thesaurus ExpansionsWhen thesaurus=true is added to the query, thesaurus expansions will be added to the search results output. These expansions can be used to expand the scope of the query to include words and word variations the user may not have thought of on their own.Thesaurus expansion only applies to keywords specified in the “q” parameter.For each keyword, different types of expansions will be provided:broader terms – These are more general terms than the one provided by the user.For example: ship transportationnarrower terms – These are more specific examples of the term entered by the user.For example: ship tankerrelated terms – These are any other terms which have any other sort of relationship to the term entered by the user.For example: ship navigationThesaurus Expansion ProcessThe steps in using thesaurus expansions are as follows:Submit a query with thesaurus=true.See XML output below.Provide a user interface for users to choose thesaurus expansion to be added back to the query.Include selections for categories, such as “all related terms” and “all related terms for term X”.Submit the chosen expansions back to the search engine with a new query.This is done with the “thesaurus.terms” parameters specified in section REF _Ref382141219 \r \h 3.2, for example:thesaurus.terms.ship=relatedthesasurus.terms.ship=tankers,yachts,warships,steamboatsXML ExampleGET dock&thesaurus=true<thesaurus> <term name="ship"> <broader> <val>transportation</val> <val>transport</val> <val>transporting</val> </broader> <narrower> <val>ships bridges</val> <val>steamboats</val> <val>hijacking of ships</val> <val>tankers</val> <val>warships</val> <val>seamanship</val> <val>yachts</val> <val>yachting</val> <val>armored vessels</val> <val>landing craft</val> <val>tank landing ships</val> <val>anchors</val> <val>anchoring</val> <val>cutters</val> <val>hospital ships</val> <val>ice-breaking vessels</val> <val>icebreakers</val> </narrower> <related> <val>freight transportation</val> <val>boats and boating</val> <val>navigation</val> <val>navigate</val> <val>shipbuilding</val> <val>shipbuilder</val> <val>steam power</val> </related> </term> <term name="dock"> <broader> <val>harbors</val> <val>hydraulic structures</val> </broader> <narrower> <val>dry docks</val> <val>drydock</val> <val>drydocking</val> </narrower> </term></thesaurus>JSON ExampleGET dock&thesaurus=true&format=json"thesaurus":{ "term":[ { "@name":"ship", "broader":[ "transportation", "transport", "transporting" ], "narrower":[ "ships bridges", "steamboats", "hijacking of ships", "tankers", "warships", "seamanship", "yachts", "yachting", "armored vessels", "landing craft", "tank landing ships", "anchors", "anchoring", "cutters", "hospital ships", "ice-breaking vessels", "icebreakers" ], "related":[ "freight transportation", "boats and boating", "navigation", "navigate", "shipbuilding", "shipbuilder", "steam power" ] }, { "@name":"dock", "broader":[ "harbors", "hydraulic structures" ], "narrower":[ "dry docks", "drydock", "drydocking" ] } ]}Complete ExampleThe following is a complete Search API response example.Note that the content is for documentation purposes only – the actual content returned by the given search will likely be different.XML ExampleGET; <header status="200" time="231"> <request path="/iapi/v1"> <action>search</action> <q>truman</q> <highlight>true</highlight> <thesaurus>true</thesaurus> <facet>true</facet> <facet.fields>subScore,fileFormat</facet.fields> <group>web</group> </request> </header> <results total="6695" offset="0" rows="25"> <result num="0" score="2.34"> <naId>7226539</naId> <opaId>desc-7226539</opaId> <title>Letter from George McGovern to Harry S. Truman</title> <parentTitle>Subject Files, 1953 - 1972</parentTitle> <titleDate>1972-08-19</titleDate> <url>; <localId>hst-ppp_93-1_18</localId> <iconType>nara/item</iconType> <creators> <val>Truman, Harry S., 1884-1972</val> </creators> <thumbnailFile>hst-ppp_93-1_18-01.jpg</thumbnailFile> <description> <arc-id>7226539</arc-id> <arc-id-desc>7226539</arc-id-desc> <title>Letter from George McGovern to Harry S. Truman</title> <title-only>Letter from George McGovern to Harry S. Truman</title-only> <local-identifier>hst-ppp_93-1_18</local-identifier> <local-identifier-desc>hst-ppp_93-1_18</local-identifier-desc> <created-timestamp>9/21/2013 14:39:46</created-timestamp> <level-of-desc level-id="NAVI"> <lod-display>Item</lod-display> </level-of-desc> . . More description fields goes here . </description> <objects> <object> <file path="./content/hst-ppp_93-1_18-01.jpg"/> <thumbnail path="./opa-rendition/thumbnails/hst-ppp_93-1_18-01-thumb.jpg" mime="image/jpeg"/> <annotations> <transcription lastModified="2014-02-21T16:22:58" isauthoritative="false" version="232"> <users total="3"> <user id="tjefferson" fullName="Thomas Jefferson" isNaraStaff="true" lastModified="2014-02-21T16:22:58" /> <user id="mstewart" fullName="Meredith Stewart" isNaraStaff="true" lastModified="2014-02-08T12:59:49"/> <user id="kmartin" lastModified="2014-02-02T08:44:12" /> </users> <text>GEORGE McGOVERN United States Senate Washington, D.C. 20510 August 19, 1972 The Honorable Harry S. Truman Independence, Missouri My dear Mr. President: It is an honor for me, as our party's candidate for President of the United States. . .</text> </transcription> </annotations> </object> <object> <file path="./content/hst-ppp_93-1_18-02.jpg"/> <thumbnail path="./opa-rendition/thumbnails/hst-ppp_93-1_18-02-thumb.jpg" mime="image/jpeg"/> </object> <object> <file path="./content/hst-ppp_93-1_18-03.jpg"/> <thumbnail path="./opa-rendition/thumbnails/hst-ppp_93-1_18-03-thumb.jpg" mime="image/jpeg"/> </object> </objects> </result> <result num="1" score="2.14"> <naId>7283002</naId> <opaId>desc-7283002</opaId> <title>Spring 1976: 7-69-1: Truman on CIA (Examining President Truman's Role in the Establishment of the Agency), by Thomas F. Troy</title> <parentTitle>Articles from "Studies in Intelligence", 1955 - 1992</parentTitle> <parentLevel>series</parentLevel> <url>; <hmsEntryNumbers> <val>A1 27</val> </hmsEntryNumbers> <iconType>nara/fileUnit</iconType> <creators> <val>Central Intelligence Agency. (12/04/1981 - )</val> </creators> <thumbnailFile>263-a1-27-box-7-69-1-0001.jpg</thumbnailFile> <description> <arc-id>7283002</arc-id> <arc-id-desc>7283002</arc-id-desc> <title>Spring 1976: 7-69-1: Truman on CIA (Examining President Truman's Role in the Establishment of the Agency), by Thomas F. Troy</title> <title-only>Truman on CIA (Examining President Truman's Role in the Establishment of the Agency), by Thomas F. Troy</title-only> <created-timestamp>1/3/2010 10:12:33</created-timestamp> <level-of-desc level-id="FU"> <lod-display>FileUnit</lod-display> </level-of-desc> . . More description fields goes here . </description> <objects> . . More objects go here . </objects> </result> . . MORE RESULTS GO HERE . </results> <webPages total="6695" offset="0" rows="25"> <result num="0" score="1.54"> <opaId>; <title>Harry S. Truman Library and Museum</title> <webArea>Harry S. Truman Library and Museum</webArea> <webAreaUrl>; <url>; <iconType>text/html</iconType> </result> <result num="1" score="1.55"> <opaId>; <title>Spring Prologue Magazine Highlights Truman's 125th Birthday</title> <webArea>: Press Releases</webArea> <webAreaUrl>; <url>; <iconType>text/html</iconType> </result> <result num="2" score="1.53"> <opaId>; <title>Truman: HST Biography</title> <url>; <webArea>Harry S. Truman Library and Museum</webArea> <webAreaUrl>; <iconType>text/html</iconType> </result> </webPages> <facets> <field name="type"> <v name="description" count="72"/> <v name="archivesWeb" count="13"/> <v name="organization" count="8"/> <v name="person" count="4"/> <v name="presidentialWeb" count="3"/> </field> <field name="fileFormat"> <v name="application/pdf" count="50"/> <v name="application/vnd.ms-powerpoint" count="17"/> <v name="video/mpeg4" count="3"/> <v name="audio/mp3" count="1"/> <v name="image/gif" count="1"/> </field> . . More facet fields go here . </facets> <highlights> <result opaId="desc-7226539"> <title>Letter from George McGovern to Harry S. &lt;em&gt;Truman&lt;/em&gt;</title> <content> <val>The Honorable Harry s. &lt;em&gt;Truman&lt;/em&gt; Independence, Missouri My dear Mr. President:...</val> <val>GEORGE McGOVERN WASHINGTON, D.C. 20510 AIR MAIL SPECIAL DELIVERY The Honorable Harry s. &lt;em&gt;Truman&lt;/em&gt; Independence, Missouri AIR MAIL SPECIAL DELIVERY...</val> </content> <creators> <val>&lt;em&gt;Truman&lt;/em&gt;, Harry S., 1884-1972</val> </creators> </result> <result opaId="desc-7283002"> <title> <val>Spring 1976: 7-69-1: &lt;em&gt;Truman&lt;/em&gt; on CIA (Examining President &lt;/em&gt;Truman&lt;/em&gt;'s Role in the Establishment of the Agency), by Thomas F. Troy</val> </title> <content> <val>Examining President Truman's role in the establishment of the Agency TRUMAN ON CIA Thomas F. Troy...</val> <val>President Harry S. Truman had his own version of his role in the establishment of the Central Intelligence Agency. He once summed it up this way: '' I got a couple of . . .</val> <val>In Truman's most extended account, in his Memoirs, he related how he discovered the lack of coordinated intelligence in Washington, asked what was being done about it, solicited advice</val> </content> </result> . . More highlight results go here . </highlights> <thesaurus> <term name="ship"> <broader> <val>transportation</val> <val>transport</val> <val>transporting</val> </broader> <narrower> <val>ships bridges</val> <val>steamboats</val> <val>hijacking of ships</val> <val>tankers</val> <val>warships</val> <val>seamanship</val> <val>yachts</val> <val>yachting</val> <val>armored vessels</val> <val>landing craft</val> <val>tank landing ships</val> <val>anchors</val> <val>anchoring</val> <val>cutters</val> <val>hospital ships</val> <val>ice-breaking vessels</val> <val>icebreakers</val> </narrower> <related> <val>freight transportation</val> <val>boats and boating</val> <val>navigation</val> <val>navigate</val> <val>shipbuilding</val> <val>shipbuilder</val> <val>steam power</val> </related> </term> <term name="dock"> <broader> <val>harbors</val> <val>hydraulic structures</val> </broader> <narrower> <val>dry docks</val> <val>drydock</val> <val>drydocking</val> </narrower> </term> </thesaurus></opa-response>JSON ExampleGET"opa-response":{ "header":{ "@status":"200", "@time":"231", "request":{ "@path":"/iapi/v1", "action":"search", "q":"truman", "highlight":"true", "thesaurus":"true", "facet":"true", "facet.fields":"subScore,fileFormat", "group":"web" } }, "results":{ "@total":"6695", "@offset":"0", "@rows":"25", "result":[ { "@num":"0", "@score":"2.34", "naId":"7226539", "opaId":"desc-7226539", "title":"Letter from George McGovern to Harry S. Truman", "parentTitle":"Subject Files, 1953 - 1972", "titleDate":"1972-08-19", "url":"", "localId":"hst-ppp_93-1_18", "iconType":"nara/item", "creators":{ "val":"Truman, Harry S., 1884-1972" }, "thumbnailFile":"hst-ppp_93-1_18-01.jpg", "description":{ "arc-id":"7226539", "arc-id-desc":"7226539", "title":"Letter from George McGovern to Harry S. Truman", "title-only":"Letter from George McGovern to Harry S. Truman", "local-identifier":"hst-ppp_93-1_18", "local-identifier-desc":"hst-ppp_93-1_18", "created-timestamp":"9/21/2013 14:39:46", "level-of-desc":{ "@level-id":"NAVI", "lod-display":"Item" }, . . More description fields goes here . }, "objects":{ "object":[ { "file":{ "@path":".\/content\/hst-ppp_93-1_18-01.jpg" }, "thumbnail":{ "@path":".\/opa-rendition\/thumbnails\/hst-ppp_93-1_18-01-thumb.jpg", "@mime":"image\/jpeg" }, "annotations":{ "transcription":{ "@lastModified":"2014-02-21T16:22:58", "@isauthoritative":"false", "@version":"232", "users":{ "@total":"3", "user":[ { "@id":"tjefferson", "@fullName":"Thomas Jefferson", "@isNaraStaff":"true", "@lastModified":"2014-02-21T16:22:58" }, { "@id":"mstewart", "@fullName":"Meredith Stewart", "@isNaraStaff":"true", "@lastModified":"2014-02-08T12:59:49" }, { "@id":"kmartin", "@lastModified":"2014-02-02T08:44:12" } ] }, "text":"GEORGE McGOVERN\n United States Senate\n Washington, D.C. 20510\n\n August 19, 1972\n\n The Honorable Harry S. Truman\n Independence, Missouri\n\n My dear Mr. President:\n\n It is an honor for me, as our party's\n candidate for President of the United States. . ." } } }, { "file":{ "@path":".\/content\/hst-ppp_93-1_18-02.jpg" }, "thumbnail":{ "@path":".\/opa-rendition\/thumbnails\/hst-ppp_93-1_18-02-thumb.jpg", "@mime":"image\/jpeg" } }, { "file":{ "@path":".\/content\/hst-ppp_93-1_18-03.jpg" }, "thumbnail":{ "@path":".\/opa-rendition\/thumbnails\/hst-ppp_93-1_18-03-thumb.jpg", "@mime":"image\/jpeg" } } ] } }, { "@num":"1", "@score":"2.14", "naId":"7283002", "opaId":"desc-7283002", "title":"Spring 1976: 7-69-1: Truman on CIA (Examining President Truman's Role in the Establishment of the Agency), by Thomas F. Troy", "parentTitle":"Articles from \"Studies in Intelligence\", 1955 - 1992", "parentLevel":"series", "url":"", "hmsEntryNumbers":{ "val":"A1 27" }, "iconType":"nara/fileUnit", "creators":{ "val":"Central Intelligence Agency. (12/04/1981 - )" }, "thumbnailFile":"263-a1-27-box-7-69-1-0001.jpg", "description":{ "arc-id":"7283002", "arc-id-desc":"7283002", "title":"Spring 1976: 7-69-1: Truman on CIA (Examining President Truman's Role in the Establishment of the Agency), by Thomas F. Troy", "title-only":"Truman on CIA (Examining President Truman's Role in the Establishment of the Agency), by Thomas F. Troy", "created-timestamp":"1/3/2010 10:12:33", "level-of-desc":{ "@level-id":"FU", "lod-display":"FileUnit" }, . . More description fields go here . }, "objects":{ "object":[ . . More objects go here . ] } } . . MORE RESULTS GO HERE . ], }, "webPages":{ "@total":"6695", "@offset":"0", "@rows":"25", "result":[ { "@num":"0", "@score":"1.54", "opaId":"", "title":"Harry S. Truman Library and Museum", "webArea":"Harry S. Truman Library and Museum", "webAreaUrl":"", "url":"", "iconType":"text/html" }, { "@num":"1", "@score":"1.55", "opaId":"", "title":"Spring Prologue Magazine Highlights Truman's 125th Birthday", "webArea":": Press Releases", "webAreaUrl":"", "url":"", "iconType":"text/html" }, { "@num":"2", "@score":"1.53", "opaId":"", "title":"Truman: HST Biography", "url":"", "webArea":"Harry S. Truman Library and Museum", "webAreaUrl":"", "iconType":"text/html" } ] }, "facets":{ "field":[ { "@name":"type", "v":[ { "@name":"description", "@count":"72" }, { "@name":"archivesWeb", "@count":"13" }, { "@name":"organization", "@count":"8" }, { "@name":"person", "@count":"4" }, { "@name":"presidentialWeb", "@count":"3" } ] }, { "@name":"fileFormat", "v":[ { "@name":"application/pdf", "@count":"50" }, { "@name":"application/vnd.ms-powerpoint", "@count":"17" }, { "@name":"video/mpeg4", "@count":"3" }, { "@name":"audio/mp3", "@count":"1" }, { "@name":"image/gif", "@count":"1" } ] } . . More facet fields go here . ], }, "highlights":{ "result":[ { "@opaId":"desc-7226539", "title":"Letter from George McGovern to Harry S. <em>Truman</em>", "content":{ "val":[ "The Honorable Harry s. <em>Truman</em> Independence, Missouri My dear Mr. President:...", "GEORGE McGOVERN WASHINGTON, D.C. 20510 AIR MAIL SPECIAL DELIVERY The Honorable Harry s. <em>Truman</em> Independence, Missouri AIR MAIL SPECIAL DELIVERY..." ] }, "creators":{ "val":"<em>Truman</em>, Harry S., 1884-1972" } }, { "@opaId":"desc-7283002", "title":{ "val":"Spring 1976: 7-69-1: <em>Truman</em> on CIA (Examining President </em>Truman</em>'s Role in the Establishment of the Agency), by Thomas F. Troy" }, "content":{ "val":[ "Examining President Truman's role in the establishment of the Agency TRUMAN ON CIA Thomas F. Troy...", "President Harry S. Truman had his own version of his role in the establishment of the Central Intelligence Agency. He once summed it up this way: '' I got a couple of . . .", "In Truman's most extended account, in his Memoirs, he related how he discovered the lack of coordinated intelligence in Washington, asked what was being done about it, solicited advice" ] } } . . More highlighted fields go here . ], }, "thesaurus":{ "term":[ { "@name":"ship", "broader":{ "val":[ "transportation", "transport", "transporting" ] }, "narrower":{ "val":[ "ships bridges", "steamboats", "hijacking of ships", "tankers", "warships", "seamanship", "yachts", "yachting", "armored vessels", "landing craft", "tank landing ships", "anchors", "anchoring", "cutters", "hospital ships", "ice-breaking vessels", "icebreakers" ] }, "related":{ "val":[ "freight transportation", "boats and boating", "navigation", "navigate", "shipbuilding", "shipbuilder", "steam power" ] } }, { "@name":"dock", "broader":{ "val":[ "harbors", "hydraulic structures" ] }, "narrower":{ "val":[ "dry docks", "drydock", "drydocking" ] } } ] }}ExportsCatalog can export search results and content in a variety of different formats with a variety of different content. Output can be viewed, printed, or downloaded for off-line processing.Specifying What Results to ExportResults can be specified in three different ways:Results from a search:POST section REF _Ref382141274 \r \h 3.2 for search parameters.Results from a stored “my list”:POST params...See section 5.3.4.2 for more information on lists.A list of OPA-ID values:POST’s-to-export>&more export params...See below for more information on export parameters.ParametersParameterDescriptionExamplesaction=exportSave the search results with additional information as a bulk export file.action=exportexport.type=brief | full | fieldsSpecifies what to export. One of:brief – All of the fields in the brief results (standard search engine results).full – All of the fields in the full content-detail page for each result.fields – Export selected fields. Specify the exact fields to export with the resultFields parameter (see below).export.type=briefexport.type=fullexport.what=list of optional items to exportWhen exporting information, the following additional items may be exported with each result:thumbnails – Thumbnails.For export.type=brief, shows only the primary thumbnail for the item.For export.type=full, exports thumbnails for digital objects.tags – Export tags attached to the record.For export.type=brief, exports tags on the description.For export.type=full, exports the tags on the description and on each ments – All comments attached to each record.For export.type=brief, exports the comments on the description.For export.type=full, exports the comments on the description and on each object.transcriptions – Transcriptions for each digital object. [Only available for export.type=full.]translations – Translations for each digital object.[Only available for export.type=full.]export.what=thumbnails,tags,commentsexport.languages=list of language codesIf export.options=translations, then list the IS0 639-3 (three letter) language codes to export.export.languages=spa,ita,deuexport.languages.all=true/falseIf export.options=translations, then use this parameter to specify that all languages should be exported.export.languages.all=trueresultFields=list of fields…If “export.type=fields”, the list of fields to export is specified with a “resultFields” parameter. See section REF _Ref379621132 \r \h 3.4 for the list of fields which can be exported.resultFields=title,naId,opaId,descriptionexport.ids=list of opa-ids…If you wish to a selected list of results (to include in the results from a search), specify a comma-separated list of OPA_IDs to export.See section REF _Ref380704093 \r \h 1.4.2 for more information on OPA_IDs.export.ids=desc-154232,desc-24242, person-4289,org-98242,desc-24242/9232.jpgexport.format=xml|json|csv|txt|pdf|htmlSpecify the format for the search results.xml – Export all metadata in XML format.json – Export all metadata in XML format.csv – Export metadata in CSV format. Not compatible with the following “export.type” options:TBD – Uncertain how to export CSV formats for complex metadata structures and multi-valued fields. Requires discussion with NARA.txt – Export metadata in text format.Incompatible with export.type=fields. Will return an error if specified.Incompatible with “export.options=thumbnails” (option will be ignored if present).pdf – Export a PDF rendition of the results.Incompatible with export.type=fields. Will return an error if specified.html – Export an HTML rendition of the results.Incompatible with export.type=fields. Will return an error if specified.export.results.format=jsonexport.bulk=true/falseIf exporting a very large number of records, records with a large number of objects, or exporting content files, then you will likely need to specify “export.bulk=true”.When export.bulk=true, a bulk export will be queued for background processing and a bulk export ID will be returned.See section REF _Ref380616157 \r \h 5.4 for getting the status of the bulk export and getting a download URL when the export file is complete.export.bulk=trueexport.bulk.content=objects|thumbnails|transcriptions|translationsWhen export.bulk=true, additional content files can also be exported. Use this parameter to specify what content files to export.objects – Digital object files attached to each result.thumbnails – Thumbnail files attached to each result.Note: objects.xml files (with annotations=full, see section REF _Ref381136677 \r \h 2.3.1.2) will be automatically exported for all results.export.bulk.content=objects,thumbnailsExamplesExport the brief results of a simple search as HTML:POST the brief results of a simple search as HTML, with thumbnails:POST v1/exports/auth ?q=truman&type=description&export.type=brief&export.format=html&export.what=thumbnailsExport the full results of a simple search as PDF, with thumbnails, tags, and comments:POST the full results of selected items as text, with transcript:POST the full results of a simple search as XML, with everything possible including all language translations:POST selected fields, including the full archival description and content metadata, from mstewart’s “HarrySTrumanResearch” list:POST all of the fields above, plus the actual content files and thumbnail files as a bulk export:POST (standard export)When exporting results which are not bulk exports, OPA will directly respond with the content.For example, if executing the following URL:POST ?q=truman&type=description&export.type=brief&export.format=htmlThe data in the response will be HTML data.Error ResponsesIf there is an error in one of the parameters, Catalog will respond with an HTTP “400” error (bad request). The content of the error will be a standard <opa-response> XML (see section REF _Ref379726032 \r \h 1.5.2) or JSON. Possible error codes included in the <opa-response> are shown below:Error CodeDescriptionParametersINVALID_PARAM_VALUEA value for a parameter is invalid.param: The parameter with the invalid value.value: The invalid value.INCOMPATIBLE_OPTIONSThe options specified are incompatible with the format specified or with the type of export requested (brief, full, or fields).what: The incompatible option.format: The incompatible format.type: The incompatible type of export.TOO_MANY_RESULTSToo many results were requested to be exported. [TBD-Maximum number of results?]Note that the maximum number of results will be different for bulk exports than simple exports.request: The number of results requested to be exported.max: The maximum number of results allowed to be exported.INVALID_FIELDOne of the fields specified in the resultFields parameter is invalid.param: The parameter which contained the invalid field.field: The invalid field name.EXTRANEOUS_PARAMOne of the parameters is extraneous. For example, export.bulk.content when export.bulk is false. Or export.languages when translations are not exported.param: The parameter which is extraneous.Bulk ExportsBulk exports from Catalog are performed using the following steps:Choose the set of results to export (either using a search query, a list of IDs, or a “My List”, see above).Initiate the bulk-export with the parameters above.Set export.bulk=true.Save the export ID number returned by Catalog, see below.This number will be used to get status on the bulk export and to download the resulting compressed file when it is ready.Get the status of the bulk download by going to:GET the bulk-download is ready, fetch the bulk download file from:GET then download the contents.See section REF _Ref379835322 \r \h 5.4 for more information on bulk export status.XML ExamplePOST; <header status="200" time="231"> <request path="/iapi/v1"> <action>export</action> <q>truman</q> <export.type>fields</export.type> <resultFields>description</resultFields> <export.format>xml</export.format> <export.bulk>true</export.bulk> <export.bulk.content>objects,thumbnails,transcriptions</export.bulk.content> </request> </header> <bulk-export exportId="42"/></opa-response>JSON ExamplePOST{ "header":{ "@status":"200", "@time":"231", "request":{ "@path":"/iapi/v1", "action":"export", "q":"truman", "export.type":"fields", "resultFields":"description", "export.format":"json", "export.bulk":"true", "export.bulk.content":"objects,thumbnails,transcriptions" } }, "bulk-export":{ "@exportId":"42" }}Search based Content DetailBeing able to page through thousands of Content Detail pages required the existence of an API method that uses the original search results query but returns the current page only, plus the ids of the previous and next ones.See sections 3.3, 3.4 and 3.5 for search request and response reference.Content Detail resultThe following is the base query that is executed to retrieve content detail results:GET parameters. . .It will contain all the search parameters that were specified in a previous brief results search to ensure the paging is done over the same result set, excluding web results.The search parameters that will be carried over are the following:q : The search querySearchType : Used only for advanced search casesFacet filters : Filters in facets will also be carried across pagessort : Specifies the value to sort on, default value is relevanceResult fields must not be specified as the expected response will always have the same structure.XML ExampleGET &rows=1&format=xml<opaResponse naId="2668751" nextNaId="6037881" opaId="desc-2668751" prevNaId="" title="Truman Doctrine" total="71035"><header status="200">...</header><content><description>...</description><objects>...</objects></content></opa-response>JSON ExampleGET? contentDetail&q=truman&offset=0 &rows=1"opaResponse":{ "header":{ "@status":"200", "time":"2015-04-16T16:11:12.253Z", "request":{ "@action":"contentDetail", "@path":"\/iapi\/v1", "format":"json", "pretty":true } }, "@total":"71035", "@naId":"2668751", "@prevNaId":"", "@nextNaId":"6037881", "@opaId":"desc-2668751", "@title":"Truman Doctrine", "content":{ "description":"...", "objects":{...} } }}JSON Example 2GEThttps:// catalog.OpaAPI/iapi/v1?SearchType=advanced&action=contentDetail&f.level=item&f.materialsType=photographsandgraphics&f.oldScope=(online+or+descriptions)&offset=1&q=truman&rows=1&sort=titleSort+asc"opaResponse":{ "header":{ "@status":"200", "time":"2015-04-16T16:11:12.253Z", "request":{ "@action":"contentDetail", "@path":"\/iapi\/v1", "format":"json", "pretty":true } }, "@total":"71035", "@naId":"2668751", "@prevNaId":"", "@nextNaId":"6037881", "@opaId":"desc-2668751", "@title":"Truman Doctrine", "content":{ "description":"...", "objects":{...} } }}As part of the S3 implementation the following parameter was added to videos stored in S3, it’s necessary to download the videos through the API instead of S3 or cloudfront to avoid security issues.downloadURL.Here is an extract of an example response containing a video:JSON ExampleGET &rows=1..."file":{ "@mime":"video \/mpeg ", "@name":"09026_2010_01_a.mpg", "@path”:"content\/rediscovery\/09026_2010_01_a.mpg", "@stream":" content\/rediscovery\/09026_2010_01_a.mpg", "@type":"primary" }...Jump to Page functionalityJump to page is achieved by specifying the page number in the offset parameter of the search. Both offset and rows parameters must always be provided and the rows parameter must always have a value of 1.JSON ExampleGET &rows=1The previous example will retrieve the 31st result page in a 0 based results list.The Jump to Page functionality will validate that the user doesn’t go beyond the limits set for it’s user type, thus if for example a maximum of 2000 search results is set for a public user, the last offset that user will be able to access is 1999.Annotations APIThe Catalog system allows users to annotate Catalog content. Annotations include transcriptions, translations, comments, and tags.The BasicsThis section describes basic information required to access and edit annotations.Annotations are attached to contentAnnotations, as the name implies, are attached to content in Catalog. Specifically:Tags and comments – Can be attached to archival descriptions, authority records, and digital?objects.Transcriptions and translations – Can be attached to digital objects.Therefore, to access or modify annotations, you will most likely need to first determine what you want to annotate, and then you can access the annotations from there.To access annotations:Authority records: Descriptions: ; /comments; /tagsDigital Objects: ; /tags; /comments; /translationsSee a map of all of the ways that annotations can be accessed in section REF _Ref379795286 \r \h 2.1.Modifying annotations requires loginIn order to make or modify an annotation, the user will need to have a registered user account and will need to log in. This will allow all contributions created or modified to be traced back to a username for the person that made the modification.See section REF _Ref379794618 \r \h 1.6 for API methods to login and maintaining credentials for API calls.Editing annotationsPeople can edit each other’s transcriptions and translations. This in contrast to tags and comments, where only the author can edit or delete their own comment, reply, or tag. Note that NARA moderators have privileged access and can delete or restore any annotation.If two users are accessing the same transcription or translation at the same time, one user will be allowed to do the edit, and the other will be locked out. The API will return the lock status of transcriptions and translations, and will return an error if an attempt is made to edit a locked annotation.Contributed Annotations by userEach user’s contributions are publically available. The User API (see section REF _Ref378769307 \r \h 5) provides a means to view all annotations made by a particular user.Annotation parameter validationAnnotations always refer to a specific NaId and may sometimes refer to an ObjectId. Due to the nature of the implementation of adds and updates it becomes necessary to validate those two values for the following cases:Adding and updating transcriptionsAdding tagsAdding and updating commentsAdding and updating translationsIn the past, NaId and ObjectId were validated against the Solr server index for every operation that required these two parameters, even for read only operations such as annotation retrieval. This created a heavy load on the Solr server and it was determined that:For read operations it’s not necessary to validate these parameters. Parameter validation can be bypassed and API would respond with a NOT_FOUND error if a specific item wasn’t present.For write operations the validation would be performed against file system.NaId is performed by validating the existence of the directory for the NaId in file system. Ingestion creates a directory for each NaID that contains all the media files and metadata for both the NaId item and its child objects.ObjectId is validated by checking for its existence within the objects.xml file that is inside the NaId directory in file system as initialized by the ingestion process.Annotations Summary InformationFor authority records, archival descriptions, and digital objects, the API provides a means for obtaining a summary of its annotations. Typically the summary is simply the counts of annotations available for the specified path.URL Paths:Annotation summaries can be accessed for any authority record, archival description, or digital object using the following URLs:Authority records: GET Descriptions: GET; Digital Objects: GET; See a map of all of the ways that annotations can be accessed in section REF _Ref379795286 \r \h 2.1.ParametersThe summary can be further customized to include detailed information any (or all) annotations, using the “include” parameter:ParameterDescriptionExamplesinclude=[tags],[comments],[transcription],[translations],[all]A comma-separated list of annotations to fetch as part of the summary.(default) if not specified, only counts for all annotations are provided.include=tags,commentsinclude=allResponseThe summary response will have four sections:<comments>Default:Only the counts (the @comments, @replies, and @total attributes)If include=comments:All of the same comment XML as described in section REF _Ref380763757 \r \h 4.3.1.<tags>Default:Only the counts (the @total attribute)If include=tags:All of the same tag XML as described in section REF _Ref379829230 \r \h 4.4.1.<transcriptions>Default:Only the attribute @hasTranscription which is “true” if a transcription exists and “false” otherwise.If include=transcript:All of the same XML as described in section REF _Ref380829077 \r \h 4.5.1.<translations>Default: Has a total count of translations, plus nested tags for each language which is currently translated.If include=translations:All of the same XML as described in section REF _Ref380879861 \r \h 4.6.1.XML ExampleGET; <comments comments="3" replies="2" total="5"> <comment id="19328" user="kmartin" created="2014-02-10T14:36:23" lastModified="2014-02-10T14:40:12"> <text>One wonders if this letter to Frm Pres. Truman was felt to be obligatory, or if there was real affection between the two.</text> <replies> <reply id="45239" user="mstewart" fullName="Meredith Stewart" naraStaff="true" created="2014-02-10T15:00:03"> <text>True, but from different generations.</text> </reply> <reply id="45422" user="mkoneni" created="2014-03-08T04:12:52" lastModified="2014-03-08T04:18:02"> <text>I'm sure they ran into each other a bunch, you know at charity functions and golf tournaments...</text> </reply> </replies> </comment> <comment id="19102" user="tjefferson" created="2014-03-08T04:12:52" isDeleted="true"/> <comment id="17024" user="rbarnes" created="2014-03-09T11:14:27"> <text>Seems rather formulaic to me. I bet a staff member wrote it.</text> </comment> </comments> <tags total="3"> <tag text="Truman Post President" user="jdoe" created="2014-02-21T16:22:58"/> <tag text="McGovern Letters" user="agullet" created="2014-02-27T18:23:47"/> <tag text="nara:president=Truman" user="mstewart" fullName="Meredith Stewart" naraStaff="true" created="2014-03-19T07:07:42"/> </tags> <transcription hasTranscription="true"/> <translations total="3"> <language code="ENG"/> <language code="ITA"/> <language code="DEU"/> </translations></annotations>JSON ExampleGET{ "comments":{ "@comments":"3", "@replies":"2", "@total":"5", "comment":[ { "@id":"19328", "@user":"kmartin", "@created":"2014-02-10T14:36:23", "@lastModified":"2014-02-10T14:40:12", "text":"One wonders if this letter to Frm Pres. Truman was felt to be obligatory, or if there was real affection between the two.", "replies":{ "reply":[ { "@id":"45239", "@user":"mstewart", "@fullName":"Meredith Stewart", "@naraStaff":"true", "@created":"2014-02-10T15:00:03", "text":"True, but from different generations." }, { "@id":"45422", "@user":"mkoneni", "@created":"2014-03-08T04:12:52", "@lastModified":"2014-03-08T04:18:02", "text":"I'm sure they ran into each other a bunch, you know at charity functions and golf tournaments..." } ] } }, { "@id":"19102", "@user":"tjefferson", "@created":"2014-03-08T04:12:52", "@isDeleted":"true" }, { "@id":"17024", "@user":"rbarnes", "@created":"2014-03-09T11:14:27", "text":"Seems rather formulaic to me. I bet a staff member wrote it." } ] }, "tags":{ "@total":"3", "tag":[ { "@text":"Truman Post President", "@user":"jdoe", "@created":"2014-02-21T16:22:58" }, { "@text":"McGovern Letters", "@user":"agullet", "@created":"2014-02-27T18:23:47" }, { "@text":"nara:president=Truman", "@user":"mstewart", "@fullName":"Meredith Stewart", "@naraStaff":"true", "@created":"2014-03-19T07:07:42" } ] }, "transcription":{ "@hasTranscription":"true" }, "translations":{ "@total":"3", "language":[ { "@code":"ENG" }, { "@code":"ITA" }, { "@code":"DEU" } ] }}Comments APIUsers can make comments on archival descriptions, authority records, objects, documents, audiovisual files, and images, and they can reply to others’ comments. Users can edit their own comments and replies, and delete them. Moderators can also delete comments.Fetching Comments and RepliesComments, with their replies, can be fetched using the following URLs:Authority records: GET commentsArchival Descriptions: GET; /commentsDigital Objects: GET; /commentsResponseThe <comments> returned by these URLs will contain the following information:@total – Total count of all comments and replies on the ment – Contains the text and replies for a comment. Has the following sub-elements:@id – The unique identifier of the comment.This can be used to permalink the comment.@isEditable – “true” if the user can modify the text of the comment, “false” otherwise.@user – The user ID of the person who created the comment.@fullName – The full name of the user.The @fullName is only included if the user wishes for the full name to be shown in place of their user ID.@naraStaff – “true” if the user is NARA staff. “false” otherwise.@lastModified – The date-time when the comment was created or last edited.@isDeleted – “true” if the comment has been deleted. “false” otherwise.text – The actual text of the comment.replies – Container for the replies of the comment. Has the following sub-elements:@total – Total count of the replies for a comment.reply – Holds the information for a single reply. Has the following sub-elements:@id – The unique identifier of the reply.@isEditable – “true” if the user can modify the text of the reply, “false” otherwise.@user – The user ID of the person who created the reply.@fullName – The full name of the replying user.The @fullName is only included if the user wishes for the full name to be shown in place of their user ID.@naraStaff – “true” if the replying user is NARA staff. “false” otherwise.@lastModified – The date-time when the reply was created or last edited.@isDeleted – “true” if the comment has been deleted. “false” otherwise.text – The actual text of a reply to the comment.XML ExampleGET /comments<comments comments="3" replies="2" total="5"> <comment id="19328" user="kmartin" created="2014-02-10T14:36:23" lastModified="2014-02-10T14:40:12"> <text>One wonders if this letter to Frm Pres. Truman was felt to be obligatory, or if there was real affection between the two.</text> <replies> <reply id="45239" user="mstewart" fullName="Meredith Stewart" naraStaff="true"created="2014-02-10T15:00:03"> <text>True, but from different generations.</text> </reply> <reply id="45422" user="mkoneni" created="2014-03-08T04:12:52"lastModified="2014-03-08T04:18:02"> <text>I'm sure they ran into each other a bunch, you know at charity functions and golf tournaments...</text> </reply> </replies> </comment> <comment id="19102" user="tjefferson" created="2014-03-08T04:12:52" isDeleted="true"/> <comment id="17024" user="rbarnes" created="2014-03-09T11:14:27"> <text>Seems rather formulaic to me. I bet a staff member wrote it.</text> </comment></comments>JSON ExampleGET /comments&format=json"comments":{ "@comments":"3", "@replies":"2", "@total":"5", "comment":[ { "@id":"19328", "@user":"kmartin", "@created":"2014-02-10T14:36:23", "@lastModified":"2014-02-10T14:40:12", "text":"One wonders if this letter to Frm Pres. Truman was felt to be obligatory, or if there was real affection between the two.", "replies":{ "reply":[ { "@id":"45239", "@user":"mstewart", "@fullName":"Meredith Stewart", "@naraStaff":"true", "@created":"2014-02-10T15:00:03", "text":"True, but from different generations." }, { "@id":"45422", "@user":"mkoneni", "@created":"2014-03-08T04:12:52", "@lastModified":"2014-03-08T04:18:02", "text":"I'm sure they ran into each other a bunch, you know at charity functions and golf tournaments..." } ] } }, { "@id":"19102", "@user":"tjefferson", "@created":"2014-03-08T04:12:52", "@isDeleted":"true" }, { "@id":"17024", "@user":"rbarnes", "@created":"2014-03-09T11:14:27", "text":"Seems rather formulaic to me. I bet a staff member wrote it." } ]}Fetching a Single Comment or ReplyTo fetch a single comment and its associated replies add the comment ID to the end of the appropriate “comments” URL:Authority Records: GET /<NAID> /comments/<comment-id>GET /<NAID> /comments/<comment-id>Archival Descriptions: GET; /comments/<comment-id>Digital Objects: GET ExampleGET /comments/19328<comment id="19328" user="kmartin" created="2014-02-10T14:36:23" lastModified="2014-02-10T14:40:12"> <text>One wonders if this letter to Frm Pres. Truman was felt to be obligatory, or if there was real affection between the two.</text> <replies> <reply id="45239" user="mstewart" fullName="Meredith Stewart" naraStaff="true" created="2014-02-10T15:00:03"> <text>True, but from different generations.</text> </reply> <reply id="45422" user="mkoneni" created="2014-03-08T04:12:52" lastModified="2014-03-08T04:18:02"> <text>I'm sure they ran into each other a bunch, you know at charity functions and golf tournaments...</text> </reply> </replies></comment>JSON ExampleGET /comments/19328?format=json{ "@id":"19328", "@user":"kmartin", "@created":"2014-02-10T14:36:23", "@lastModified":"2014-02-10T14:40:12", "text":"One wonders if this letter to Frm Pres. Truman was felt to be obligatory, or if there was real affection between the two.", "replies":{ "reply":[ { "@id":"45239", "@user":"mstewart", "@fullName":"Meredith Stewart", "@naraStaff":"true", "@created":"2014-02-10T15:00:03", "text":"True, but from different generations." }, { "@id":"45422", "@user":"mkoneni", "@created":"2014-03-08T04:12:52", "@lastModified":"2014-03-08T04:18:02", "text":"I'm sure they ran into each other a bunch, you know at charity functions and golf tournaments..." } ] }}Modifying Comments and RepliesThis section deals with creating, editing, and deleting comments and/or replies. If a comment or a reply is to be edited or deleted, the comment-id (for comments) or both the comment ID and the reply ID (for replies) are given in the URL. For example:Creating comments: POST. . . /comments?text=<new comment text here>Updating comments: PUT. . . /comments/<comment-id>?text=<new comment text here>Deleting comments: DELETE. . . /comments/<comment-id>Creating replies: POST. . . /comments/<comment-id>?text=<new reply text here>Updating replies: PUT. . . /comments/<comment-id>/<reply-id>?text=<new reply text here>Deleting replies:DELETE. . . /comments/<comment-id>/<reply-id>ParametersThe following table shows the Comments API parameters.ParameterDescriptionExamplestext=comment-or-reply-textSpecifies the text of the comment or reply to be created or used for the update (edit).text=In my opinion the reason for the change had to do with the prevailing political opinion. . .Examples:Creating a new comment on a description:POST /comments?text=Comment text goes here . . .Creating a new comment on a digital object:POST text goes here . . .Creating a new comment on an authority record:POST /1090294 /comments?text=Comment text goes here . . .Updating a comment:PUT /comments/19328?text=Comment text goes here . . .Deleting a comment:DELETE a reply:PUT /comments/19328/152?text=Reply text goes here . . .Deleting a reply:DELETE /comments/19328/152ResponseA "200" response indicates that the comment or reply was created/updated/deleted successfully. See section REF _Ref379726032 \r \h 1.5.2 for more information on the general response structure.When creating replies or comments, the new comment ID / reply ID will be returned in the response.XML Example (create comment)POST text goes here . . .<opa-response> <header status="200" time="231"> <request path="/iapi/v1/holdings/7226539/comments"> <action>create</action> <text>Comment text goes here . . .</text> </request> </header> <comment id="19423"/></opa-response>JSON Example (create comment)POST text goes here . . .{ "header":{ "@status":"200", "@time":"231", "request":{ "@path":"/iapi/v1/holdings/7226539/comments", "action":"create", "text":"Comment text goes here . . ." } }, "comment":{ "@id":"19423" }}XML Example (create a reply to a comment)POST text goes here. . .<opa-response> <header status="200" time="231"> <request path="/iapi/v1/holdings/7226539/comments/19423"> <action>create</action> <text>Reply text goes here. . .</comment> </request> </header> <comment id="19423"> <reply id="15823"/> </comment></opa-response>JSON Example (create a reply to a comment)POST text goes here. . ."opa-response":{ "header":{ "@status":"200", "@time":"231", "request":{ "@path":"/iapi/v1/holdings/7226539/comments/19423", "action":"create", "text":"Reply text goes here. . ." } }, "comment":{ "@id":"19423", "reply":{ "@id":"15823" } }}Error CodesThe following error codes are currently defined as part of the API response:Error CodeDescriptionParametersEMBEDDED_HTMLThe comment or reply text contains embedded HTML characters which implies a potential cross-site scripting attack.param: The parameter where the embedded HTML was MENT_SIZE_EXCEEDEDThe size of the comment or reply (number of characters) is too large. Comments and replies cannot be larger than [TBD comment size limit] UTF-8 characters long.request: The size of the comment or reply requested.max: The maximum number of characters allowed in a comment or MENT_NOT_FOUNDThe specified comment or reply doesn’t exist and cannot be deleted, edited or replied ment: The identifier value for the comment or reply that does not exist.REPLY_NOT_FOUNDThe specified reply doesn’t exist (or doesn’t exist within the specified comment ID) and cannot be deleted, edited or replied ment: The identifier of the comment.reply: The identifier of the reply.ILLEGAL_CHARACTERSComment or reply rejected because it contains illegal (for example, non-printable) characters.noneNOT_LOGGED_INAttempted to create or modify a comment or reply without logging in.noneNOT_OWNERAttempted to edit or delete someone else’s comment or reply.request: The user ID who requested to delete the comment or reply.owner: The user ID who owns the comment or reply.Bulk Import of CommentsWhen bulk importing comments, the following elements are expected:comments – Identifies that this is a list of comments.naId – Specify the NARA ID for the comment.NOTE: No “type” is required (e.g. “person”, “organization”, “description”, etc.). objectId – [OPTIONAL] Specify the object ID (within the specified NAID) of the object to which the comment is attached.text – Specifies the text of the comment.JSON Example:{ "comments":[ { "naId":"19328", "text":"One wonders if this letter to Frm Pres. Truman was felt to be obligatory, or if there was real affection between the two." }, { "naId":"17024", "objectId":"32", "text":"Seems rather formulaic to me. I bet a staff member wrote it." } ]}Tagging APIUsers can download tags for archival descriptions, authority records, and digital objects.A logged-in user can delete their own tags. There is no facility for updating a tag, instead you would need to delete the tag and add a new one.Users can also create machine tags, which look like the following:geo:latitude=70.232Which will be encoded in the URL as follows:text=geo%3Alatitude%3D70.232Fetching TagsTags can be fetched using the following URLs:Authority Records:GET Descriptions:GET Objects:GET; /tagsThe content returned by these URLs will contain the following information inside <tags>:@total – Total count of all tags on the item.tag – Detailed information on an individual tag. This contains the following sub-elements:@text – The actual text of the tag.Tag text is considered to be case insensitive when matching tags and all whitespace is normalized.@user – The user ID of the person who created the tag.@fullName – The full name of the user.The @fullName tag is only included if the user wishes for the full name to be shown in place of their user ID.@isNaraStaff – “true” if the user is NARA staff. “false” otherwise.@created – The date-time when the tag was created.Fetching a list of tagsTo fetch all of the tags on an archival description, authority record, or digital object, fetch the contents of the appropriate “tags” URL.XML ExampleGET total="3"> <tag text="Truman Post President" user="jdoe" created="2014-02-21T16:22:58"/> <tag text="McGovern Letters" user="agullet" created="2014-02-27T18:23:47"/> <tag text="nara:president=Truman" user="mstewart" fullName="Meredith Stewart" naraStaff="true" created="2014-03-19T07:07:42"/></tags>JSON ExampleGET{ "@total":"3", "tag":[ { "@text":"Truman Post President", "@user":"jdoe", "@created":"2014-02-21T16:22:58" }, { "@text":"McGovern Letters", "@user":"agullet", "@created":"2014-02-27T18:23:47" }, { "@text":"nara:president=Truman", "@user":"mstewart", "@fullName":"Meredith Stewart", "@naraStaff":"true", "@created":"2014-03-19T07:07:42" } ]},Fetching a single tagTo fetch a single tag, add the tag to the end of the URL:Authority Records:GET /<NAID>/tags?text=<tag>Archival Descriptions:GET Objects:GET; /tags?text=<tag>Note that special characters (such as spaces and ‘#’) will need to be URL encoded.XML ExampleGET text="McGovern Letters" user="agullet" created="2014-02-27T18:23:47"/>JSON ExampleGET{ "@text":"McGovern Letters", "@user":"agullet", "@created":"2014-02-27T18:23:47"}Modifying TagsTags can be modified using the appropriate HTTP method and specifying the text of the tag:Creating tags: POST. . . /tags?text=<new tag text here>Deleting tags: DELETE. . . /tags?text=<tag>ParametersThe following table shows the Tagging API parameters.ParameterDescriptionExamplestext=tag-textSpecify the text of the tag to be added or deleted.Multiple text= parameters can be specified to write multiple tags.text=McGovern%20Letterstext=nara%3Alatitude%3d47.22(note encoding of special URL characters)Examples:Creating a new tag on a description:POST Creating two new tags on a description:POST a new tag on a digital object:POST Creating a new tag on an authority record:POST /1090294/tags?text=VP%20Candidate%20Shriver Deleting a tag:DELETE ResponseThe response will the standard Catalog response (see section REF _Ref379726032 \r \h 1.5.2 for more information).Error CodesThe following error codes are currently defined as part of the API response. Note that if multiple tags are specified (i.e. with multiple “text” parameters) then there may be multiple errors in the response (for every tag which was in error).No tag will be added unless all tags are error-free.Error CodeDescriptionParametersEMBEDDED_HTMLThe tag text contains embedded HTML characters which implies a potential cross-site scripting attack.param: The parameter where the embedded HTML was detected.TAG_SIZE_EXCEEDEDThe size of the tag (number of characters) is too large. Tags cannot be larger than [TBD tag size limit] UTF-8 characters long.tag: The tag value which exceeds the size limit.request: The size of the tag requested.max: The maximum number of characters allowed in a tag.TAG_ALREADY_EXISTSThe specified tag has already been created by someone else.tag: The tag value which already exists.ILLEGAL_CHARACTERSTag rejected because it contains illegal (for example, non-printable) characters.noneNOT_LOGGED_INThis will be returned for users who attempt to create a tag without logging in.noneNOT_OWNERThis will be returned for users who attempt to delete someone else’s tag.request: The user ID who requested to delete the tag.owner: The user ID who owns the tag.Bulk Import of TagsWhen bulk importing tags, the following elements are expected:tags – Identifies that this is a list of tags.naId – Specify the NARA ID for the tag.NOTE: No “type” is required (e.g. “person”, “organization”, “description”, etc.). objectId – [OPTIONAL] Specify the object ID (within the specified NAID) of the object to which the tag is attached.text – Specifies the text of the tag.JSON Example{ "tags":[ { "naId":"19328", "text":"Truman Post President" }, { "naId":"19328", "text":"McGovern Letters" }, { "naId":"7205115", "objectId":"1936360", "text":"nara:president=Truman" } ]}Transcription APIUsers can create transcriptions for digital objects stored in Catalog. Each object can have at most one transcription. Users can also edit transcriptions – both those they create and those created by others, with one exception. Only authorized users can modify an authoritative transcription.Notes:You must be logged in to create or modify transcriptions.Anyone can edit anyone else’s transcription.Only moderators can delete transcriptions.Fetching a TranscriptionNote that there is only one transcription per digital object. A transcription can be fetched using the following URL:GET; /transcriptionsResponseThe URL will return the following information in the <transcription> tag:@lastModified – The date-time when the transcription was last modified.@isLocked – “true” if the transcription is currently locked by another user, “false” otherwise .@isAuthoritative – “true” if this is an authoritative transcription, “false” otherwise.@version – The version number of the latest transcription.This number will increment for every modification (including deletes and restores) made to the transcription.lockedBy – Holds information on the user who has locked the transcription. Contains the following sub-elements:@id – The user ID of the user (for example, “kmartin”).@fullName – The full name of the user. Attribute is only present if the user wishes to make their full name public.@isNaraStaff – “true” if the user is NARA staff. “false” otherwise. @when – The date-time when the lock was initiated.users – Parent tag which contains a list of the users who have contributed to this transcription. Contains the following sub-elements:@total – Total number of unique users who have contributed to the transcription.user – Information on an individual user who helped contribute to the transcription. Contains the following sub-elements:@id – The user ID of the user (for example, “kmartin”).@fullName – The full name of the user. Attribute is only present if the user wishes to make their full name public.@isNaraStaff – “true” if the user is NARA staff. “false” otherwise.@lastModified – The date-time when this user last modified the transcription.text – The actual text of the transcription.Note that users will be automatically sorted by @lastModified date (most recent modifier first).XML ExampleGET lastModified="2014-02-21T16:22:58" isLocked="true" isauthoritative="false" version="232"> <lockedBy id="gwashington" when="2014-02-22T10:08:41"/> <users total="3"> <user id="tjefferson" fullName="Thomas Jefferson" isNaraStaff="true" lastModified="2014-02-21T16:22:58" /> <user id="mstewart" fullName="Meredith Stewart" isNaraStaff="true" lastModified="2014-02-08T12:59:49"/> <user id="kmartin" lastModified="2014-02-02T08:44:12" /> </users> <text>GEORGE McGOVERNUnited States SenateWashington, D.C. 20510August 19, 1972The Honorable Harry S. TrumanIndependence, MissouriMy dear Mr. President: It is an honor for me, as our party'scandidate for President of the United States. . .</text></transcription>JSON ExampleGET /transcriptions?format=json{ "@lastModified":"2014-02-21T16:22:58", "@isLocked":"true", "@isauthoritative":"false", "@version":"232", "lockedBy":{ "@id":"gwashington", "@when":"2014-02-22T10:08:41" }, "users":{ "@total":"3", "user":[ { "@id":"tjefferson", "@fullName":"Thomas Jefferson", "@isNaraStaff":"true", "@lastModified":"2014-02-21T16:22:58" }, { "@id":"mstewart", "@fullName":"Meredith Stewart", "@isNaraStaff":"true", "@lastModified":"2014-02-08T12:59:49" }, { "@id":"kmartin", "@lastModified":"2014-02-02T08:44:12" } ] }, "text":"GEORGE McGOVERN\nUnited States Senate\nWashington, D.C. 20510\n\nAugust 19, 1972\n\nThe Honorable Harry S. Truman\nIndependence, Missouri\n\nMy dear Mr. President:\n\n It is an honor for me, as our party's\ncandidate for President of the United States. . ."}Modifying TranscriptionsThe APIs provide a method to “lock” a transcription so that it cannot be edited by other users during the current user’s session.When a transcription is fetched information about its lock status – @isLocked – at that moment is returned. However, the transcription could be locked by another user before the current user begins editing. If it is locked, the API will return an error, and indicate what username currently holds the lock.Use the following URL to lock, unlock, or save the transcription:PUT; /transcriptions?params… Notes:The user must be logged in to modify transcriptions.Only authorized users (NARA Staff) can modify or create authoritative transcriptionsYou must obtain a lock before you can save a transcription.ParametersParameterDescriptionExamplesaction=lock|saveAndRelock|saveAndUnlock|unlockIndicates what to do with the transcription. Choices are:lock – obtain a lock for the transcription, if not locked, so the transcription can be edited.Locks expire after 30 minutes.To refresh the lock, use action=lock again.action=lock will return a fresh copy of the current transcription.saveAndRelock – save the transcription and keep the lock.The lock is refreshed so that the user has 30 more minutes before the lock expires.saveAndUnlock – save the transcription and release the lock.unlock – cancel the editing session and release the lock.action=lockaction=saveAndRelockaction=saveAndUnlockaction=unlocktext=text-of-transcriptSpecifies the text of the transcript to be created or used for the replacement (saving).text=This%20document%20is%20the%20reference%20guide%20for%20the%20OPA%20APIs (note encoding of special URL characters)isAuthoritative=true | falseSet the “isAuthoritative” flag for the transcription. Can only be done by authorized users (NARA Staff).isAuthoritative=trueExamples:Locking a transcription for edit:PUT /transcriptions?action=lock Saving a transcription on a digital object and releasing the lock:PUT /transcriptions?action=saveAndUnlock&text=The text of the transcription goes here . . .Saving a transcription on a digital object and keeping the lock:PUT /transcriptions?action=saveAndRelock&text=The text of the transcription goes here . . .Releasing the lock without saving anything:PUT /transcriptions?action=unlock Response for action=lockTo absolutely ensure that the user is editing the latest version of a transcription, the response for action=lock will return a fresh copy of the <transcription> as specified above (section REF _Ref380829077 \r \h 4.5.1).Note that, like all actions, the transcription returned will be nested inside of an <opa-response> tag (see examples below). If the lock can not be obtained, an error is returned.XML ExamplePUT /transcriptions?action=lock<opa-response> <header status="200" time="132"><request path="/iapi/v1/holdings/7223928/objects/263/annotations/transcription"> <action>lock</action></request> </header> <transcription lastModified="2014-02-21T16:22:58"isLocked="true" isauthoritative="false" version="232"> . . Transcription users and text will be here (see section REF _Ref380829077 \r \h 4.5.1) . This is the text that should be provided to the user to edit. . </transcription></opa-response>JSON ExamplePUT /transcriptions?action=lock{ "header":{ "@status":"200", "@time":"132", "request":{ "@path":"/iapi/v1/holdings/7223928/objects/263/annotations/transcription", "action":"lock" } }, "transcription":{ "@lastModified":"2014-02-21T16:22:58", "@isLocked":"true", "@isauthoritative":"false", "@version":"232", . . Transcription users and text will be here (see section REF _Ref380829077 \r \h 4.5.1) . This is the text that should be provided to the user to edit. .}Response for Other ActionsThe response will the standard Catalog response (see section REF _Ref379726032 \r \h 1.5.2 for more information).Error CodesThe following error codes are currently defined as part of the API response:Error CodeDescriptionParametersEMBEDDED_HTMLThe transcription text contains embedded HTML characters which imply a potential cross-site scripting attack.param: The parameter where the embedded HTML was detected.NO_LOCKTried to save a transcription to a digital object without first acquiring a lock.noneLOCKED_BY_ANOTHERTranscription currently locked by someone else.user: The username of the user currently editing the transcription.when: When the other user initiated the lock.ILLEGAL_CHARACTERSTranscription rejected because it contains illegal (for example, non-printable) characters.noneNOT_LOGGED_INThis will be returned for users who attempt to save or lock a transcription without logging in.noneNOT_AUTHORIZEDThis will be returned for unauthorized users who attempt to edit an authoritative transcription, OR for unauthorized users who attempt to set the “isAuthoritative” flag.request: The user ID who requested to edit the authoritative transcript.Bulk Import of TranscriptionsWhen bulk importing transcriptions, the following elements are expected:transcriptions – Identifies that this is a list of transcriptions.naId – Specify the NARA ID for the transcription.NOTE: No “type” is required (e.g. “person”, “organization”, “description”, etc.). This is optional for objects. Objects just need objectIdobjectId – Specify the object ID (within the specified NAID) of the object to which the transcription is attached. Note: For transcriptions, the objectId is required.text – Specifies the text of the transcription.JSON Example{ "transcriptions":[ { "naId":"7205115", "objectId":"1936351", "text":"GEORGE McGOVERN\n United States Senate\n Washington, D.C. 20510\n\n August 19, 1972\n\n The Honorable Harry S. Truman\n Independence, Missouri\n\n My dear Mr. President:\n\n It is an honor forme, as our party's\n candidate for President of the United States. . ." }, { "naId":"2668751", "objectId":"203578", "text":"GEORGE McGOVERN\n United States Senate\n Washington, D.C. 20510\n AIRMAIL" } ]}Translation APIUsers can translate the text in digital objects and have those translations stored in Catalog. Users can choose to translate into almost any language (see section REF _Ref380833907 \r \h 6.4 for a list of all languages). A single digital object can hold multiple translations for multiple languages, but there can be only one translation for a particular language.Users can also edit translations – both those they create and those created by others, with one exception. Only authorized users can modify an authoritative translation.Notes:You must be logged in to create or modify translations.Anyone can edit anyone else’s translation.Only moderators can delete translations.Fetching a List of all TranslationsA list of all available translations can be fetched from a digital object using the following URL:GET; /translationsResponseParameterDescriptionExamplesfull=true|falseSpecify if the full text and metadata should be retrieved for all translations.Without full=true, a summary of the translations will be returned. See section REF _Ref381131774 \r \h 4.6.1.1.full=trueResponseThe data returned by this call includes the following inside the <translations> tag:@total – The total number of available translations for the object.translation/@code – The language code for an available translation.This is the ISO 639-3 (three-letter) code for the language.See section REF _Ref380833907 \r \h 6.4 for a list of the languages supported by NARA.Fetching a summary of translationsThe default method for fetching translations fetches a list of the languages which have been translated for the digital object:XML ExampleGET /translations<translations total="3"> <translation code="eng"/> <translation code="ita"/> <translation code="deu"/></translations>JSON ExampleGET /translations?format=json{ "@total":"3", "translation":[ { "@code":"eng" }, { "@code":"ita" }, { "@code":"deu" } ]}Fetching a list of full translationsAdd the “full=true” parameter to fetch the complete translation text and metadata for all translations. See section REF _Ref380934298 \r \h 4.6.2 below for a complete description of all of the metadata fields found in a full translation.XML ExampleGET /translations?full=true<translations total="3"> <translation code="ita" lastModified="2014-02-21T16:22:58" isLocked="true" isauthoritative="false" version="232"> <lockedBy id="gwashington" when="2014-02-22T10:08:41"/> <users total="3"> <user id="tjefferson" fullName="Tomás Jefferson" isNaraStaff="true" lastModified="2014-02-21T16:22:58" /> <user id="gwashington" fullName="Giorgio Washington" isNaraStaff="true" lastModified="2014-02-08T12:59:49"/> </users> <text>George McGovern Senato degli Stati Uniti Washington, D.C. 20510 19 ago 1972 L'Onorevole Harry S. Truman Independence, Missouri Mio caro Signor Presidente: E 'un onore per me, come il nostro partito di candidato alla Presidenza degli Stati Uniti. .</text> </translation> <translation code="spa"> . . Full information on the Spanish translation goes here . </translation> <translation code="deu"> . . Full information on the German translation goes here . </translation></translations>JSON ExampleGET /translations?full=true&format=json"translations":{ "@total":"3", "translation":[ { "@code":"ita", "@lastModified":"2014-02-21T16:22:58", "@isLocked":"true", "@isauthoritative":"false", "@version":"232", "lockedBy":{ "@id":"gwashington", "@when":"2014-02-22T10:08:41" }, "users":{ "@total":"3", "user":[ { "@id":"tjefferson", "@fullName":"Tom?s Jefferson", "@isNaraStaff":"true", "@lastModified":"2014-02-21T16:22:58" }, { "@id":"gwashington", "@fullName":"Giorgio Washington", "@isNaraStaff":"true", "@lastModified":"2014-02-08T12:59:49" } ] }, "text":"George McGovern \n\n Senato degli Stati Uniti \n Washington, D.C. 20510 \n\n 19 ago 1972 \n\n L'Onorevole Harry S. Truman \n Independence, Missouri \n\n Mio caro Signor Presidente: \n\n E 'un onore per me, come il nostro partito di \n candidato alla Presidenza degli Stati Uniti. ." }, { "@code":"spa", . . Full information on the Spanish translation goes here . }, { "@code":"deu", . . Full information on the German translation goes here . } ]}Fetching a TranslationNote that there is only one translation per digital object. A translation can be fetched using the following URL:GET; /translations/<lang-code>The <lang-code> in the above example will be the ISO 639-3 (three-letter) code for the language. See section REF _Ref380833907 \r \h 6.4 for a list of all languages supported by NARA.ResponseThe URL will return the following information in the <translation> tag:@code – The language code of the language.This is the ISO 639-3 (three-letter) code for the language.See section REF _Ref380833907 \r \h 6.4 for a list of the languages supported by NARA.@lastModified – The date-time when the translation was last modified.@isLocked – “true” if the translation is currently locked by another user, “false” otherwise.@isAuthoritative – “true” if this is an authoritative translation, “false” otherwise.@version – The version number of the latest translation.This number will increment for every modification (including deletes and restores) made to the translation.lockedBy – Holds information on the user who has locked the translation. Contains the following sub-elements:@id – The user ID of the user (for example, “kmartin”).@fullName – The full name of the user. Attribute is only present if the user wishes to make their full name public.@isNaraStaff – “true” if the user is NARA staff. “false” otherwise. @when – The date-time when the lock was initiated.users – Parent tag which contains a list of the users who have contributed to this translation. Contains the following sub-elements:@total – Total number of unique users who have contributed to the translation.user – Information on an individual user who helped contribute to the translation. Contains the following sub-elements:@id – The user ID of the user (for example, “kmartin”).@fullName – The full name of the user. Attribute is only present if the user wishes to make their full name public.@isNaraStaff – “true” if the user is NARA staff. “false” otherwise.@lastModified – The date-time when this user last modified the translation.text – The actual text of the translation.Note that users will be automatically sorted by @lastModified date (most recent modifier first).XML ExampleGET /translations/ita<translation code="ita" lastModified="2014-02-21T16:22:58"isLocked="true" isauthoritative="false" version="232"> <lockedBy id="gwashington" when="2014-02-22T10:08:41"/> <users total="3"> <user id="tjefferson" fullName="Tomás Jefferson" isNaraStaff="true" lastModified="2014-02-21T16:22:58" /> <user id="gwashington" fullName="Giorgio Washington" isNaraStaff="true"lastModified="2014-02-08T12:59:49"/> </users> <text>George McGovern Senato degli Stati Uniti Washington, D.C. 20510 19 ago 1972 L'Onorevole Harry S. Truman Independence, Missouri Mio caro Signor Presidente: E 'un onore per me, come il nostro partito di candidato alla Presidenza degli Stati Uniti. .</text></translation>JSON ExampleGET /translations/ita&format=json{ "@code":"ita", "@lastModified":"2014-02-21T16:22:58", "@isLocked":"true", "@isauthoritative":"false", "@version":"232", "lockedBy":{ "@id":"gwashington", "@when":"2014-02-22T10:08:41" }, "users":{ "@total":"3", "user":[ { "@id":"tjefferson", "@fullName":"Tomás Jefferson", "@isNaraStaff":"true", "@lastModified":"2014-02-21T16:22:58" }, { "@id":"gwashington", "@fullName":"Giorgio Washington", "@isNaraStaff":"true", "@lastModified":"2014-02-08T12:59:49" } ] }, "text":"George McGovern \n\nSenato degli Stati Uniti \nWashington, D.C. 20510 \n\n19 ago 1972 \n\nL'Onorevole Harry S. Truman \nIndependence, Missouri \n\nMio caro Signor Presidente: \n\n E 'un onore per me, come il nostro partito di \ncandidato alla Presidenza degli Stati Uniti. ."}Modifying TranslationsThe APIs provide a method to “lock” a translation so that it cannot be edited by other users during the current user’s session.When a translation is fetched information about its lock status – @isLocked – at that moment is returned. However, the translation could be locked by another user before the current user begins editing. If it is locked, the API will return an error, and indicate what username currently holds the lock.Use the following URL to modify the translation for a digital object:PUT; /translation/<lang-code>?params… Notes:The user must be logged in to modify translations.Only authorized users (NARA Staff) can modify or create authoritative translations.You must obtain a lock before you can save a translation.ParametersParameters for modifying translations are given in the following table.ParameterDescriptionExamplesaction=lock|saveAndRelock|saveAndUnlock|unlockIndicates what to do with the translation. Choices are:lock – obtain a lock for the translation, if not locked, so the translation can be edited.Locks expire after 30 minutes.To refresh the lock, use action=lock again.action=lock will return a fresh copy of the current translation.saveAndRelock – save the translation and keep the lock.The lock is refreshed so that the user has 30 more minutes before the lock expires.saveAndUnlock – save the translation and release the lock.unlock – cancel the editing session and release the lock.action=lockaction=saveAndRelockaction=saveAndUnlockaction=unlocktext=text-of-translationSpecifies the text of the translation to be created or used for the replacement (saving).text=Il%20testo%20della%20traduzione%20va%20qui (note encoding of special URL characters)isAuthoritative=true | falseSet the “isAuthoritative” flag for the translation. Can only be done by authorized users (NARA Staff).isAuthoritative=trueExamples:Locking the Italian translation for edit:PUT /translations/ita?action=lock Saving an Italian translation on a digital object and releasing the lock:PUT /translations/ita?action=saveAndUnlock&text=The text of the translation goes here . . .Saving an Italian translation on a digital object and keeping the lock:PUT /translations/ita?action=saveAndRelock&text=Il testo della traduzione va qui. . .Releasing the lock without saving anything:PUT /translations/ita?action=unlock Response for action=lockTo absolutely ensure that the user is editing the latest version of a translation, the response for action=lock will return a fresh copy of the <translation> as specified above (section REF _Ref380879861 \r \h 4.6.1).The translation returned will be nested inside of an <opa-response> tag:XML ExamplePUT /translations/ita?action=lock <opa-response> <header status="200" time="132"><request path="/iapi/v1/holdings/7226539/content/263.jpg#translation"> <action>lock</action></request> </header> <translation code="ita" lastModified="2014-02-21T16:22:58"isLocked="true" isauthoritative="false" version="232"> . . Translation users and text will be here (see section REF _Ref380829077 \r \h 4.5.1) . This is the text that should be provided to the user to edit. . </translation></opa-response>JSON ExamplePUT /translations/ita?action=lock&format=json{ "header":{ "@status":"200", "@time":"132", "request":{ "@path":"/iapi/v1/holdings/7226539/content/263.jpg#translation", "action":"lock" } }, "translation":{ "@lastModified":"2014-02-21T16:22:58", "@isLocked":"true", "@isauthoritative":"false", "@version":"232", . . Translation users and text will be here (see section REF _Ref380829077 \r \h 4.5.1) . This is the text that should be provided to the user to edit. .}Response for Other ActionsAll other translation actions will the standard Catalog response (see section REF _Ref379726032 \r \h 1.5.2 for more information).Error CodesThe following error codes are currently defined as part of the API response:Error CodeDescriptionParametersEMBEDDED_HTMLThe translation text contains embedded HTML characters which imply a potential cross-site scripting attack.param: The parameter where the embedded HTML was detected.NO_LOCKTried to save a translation to a digital object without first acquiring a lock.noneLOCKED_BY_ANOTHERTranslation currently locked by someone else.user: The username of the user currently editing the translation.when: When the other user initiated the lock.ILLEGAL_CHARACTERSTranslation rejected because it contains illegal (for example, non-printable) characters.noneNOT_LOGGED_INThis will be returned for users who attempt to save or lock a translation without logging in.noneNOT_AUTHORIZEDThis will be returned for unauthorized users who attempt to edit an authoritative translation, OR for unauthorized users who attempt to set the “isAuthoritative” flag.request: The user ID who requested to edit the authoritative translation.Bulk Import of TranslationsWhen bulk importing translations, the following elements are expected:translations – Identifies that this is a list of translations.naId – Specify the NARA ID for the translation.NOTE: No “type” is required (e.g. “person”, “organization”, “description”, etc.). This is optional for objects. Objects just need objectIdobjectId – Specify the object ID (within the specified NAID) of the object to which the translation is attached. Note: For translations, the objectId is required.langCode – Specify the ISO-639-3 (three-letter) language code of the language of the translation.text – Specifies the text of the translation.JSON Example{ "translations":[ { "naId":"19328", "objectId":"1", "langCode":"ita", "text":"George McGovern \n\n Senato degli Stati Uniti \n Washington, D.C. 20510 \n\n 19 ago 1972 \n\n L'Onorevole Harry S. Truman \n Independence, Missouri \n\n Mio caro Signor Presidente: \n\n E 'un onore per me, come il nostro partito di \n candidato alla Presidenza degli Stati Uniti. ." }, { "naId":"19328", "objectId":"1", "langCode":"spa", "text":"George McGovern \n Senado de Estados Unidos \n Washington, DC 20510 \n\n 19 de agosto 1972 \n\n El Honorable Harry S. Truman \n Independence, Missouri \n\n Mi querido Se?or Presidente: \n\n Es un honor para mí, como nuestro grupo de \n candidato a Presidente de los Estados Unidos. . ." } ]}User Contributions and Activities APIOnce a user creates an account, he or she can annotate content, save search results to lists, and track downloads. This API provides capabilities to list annotations and activity-related information from the user perspective.This section discusses fetching the contributions for a user, including summary information, but does not deal with creating or modifying annotations (see section REF _Ref378769779 \r \h 4).User Summary InformationA summary of user information is available by accessing the user’s URLs:GET will return a summary of all of the contributions made by the user, and (if the user requested is the same as the logged-in user) the number of lists, notifications, bulk-exports, and account information.The information returned is shown below for all users:id – The user ID of the user.fullName – The user’s full name. Only shown if the user has chosen to display their full name to the public.isNaraStaff – “true” if the user is a NARA staff member.contributions – As summary of the contributions made by the user.See section REF _Ref380615854 \r \h 5.2 below for more details.The information returned is shown below only of the logged-in user is the requested user:notifications/total – A count of the unread notifications the user has.See section REF _Ref380616279 \r \h 5.5 for more information on notifications.userLists/total – The total number of lists saved by the user.See section REF _Ref379616946 \r \h 5.3 for more information on lists.accountExportsStatusSummary/Pending – The number of bulk exports in process for the user.See section REF _Ref380616157 \r \h 5.4 for more information on bulk exports.accountExportsStatusSummary/Ccompleted – The number of bulk exports completed and waiting to be downloaded.user – Detailed account information.See section REF _Ref380862797 \r \h 5.6 for more information on account information.XML ExampleGET; <id>tjefferson</id> <type>registeredUser</type> <fullName>Thomas Jefferson</fullName> <displayFullname>true</displayFullname> <email>thomas.jefferson@</email></user>JSON ExampleGET{ "user":{ "id":"tjefferson", "type":"registeredUser", "fullName":"Thomas Jefferson", "displayFullname":"true", "email":"thomas.jefferson@" }}User ContributionsAnnotations made by an individual user can be obtained by supplying the username of the user that created or modified them. For example, a user interface may wish to allow a user to view just their own annotations (“My Contributions”). It is also possible for a user to view other users’ contributions.If multiple users have contributed to an annotation, the annotation can be obtained with any of those usernames.Specific categories of user contributions can be fetched using the following URLs:GET summary of all of the user’s contributions. Can either be a simple count of contributions by type of annotation, or can contain more statistical information.GET of comments contributed by the user.GET of all unique tags contributed by the user.GET of everything tagged by the user with the specified tag.GET contributions/transcriptions?username=<user-name>List of transcriptions created or modified by the user.GET contributions/translations?username=<user-name>List of translations created or modified by the user.Note 1: The listings of entities that have transcriptions, translations, comments, and a particular tag can all be paginated. The listings are returned by default in reverse date order (newest first). Pagination and sorting are controllable by parameters given below in section REF _Ref380661158 \r \h 5.2.2 (common parameters for contributions).Note 2: The “contributed” prefixed on these paths is used to avoid confusion with the standard “comments”, “tags”, “transcriptions” and “translations” tags because the two sets of tags return different metadata structures.Contributions Summary The contribution summary can be fetched using the following URL:GET that there are two versions of this URL. One provides the full statistical information, and a second (faster and more efficient) version only provides the total counts.The simple statistics include the following:@total – Total contributions made over all time.tags/@total – Total tags created over all ments/@total – Total comments (+ replies) contributed over all time.transcriptions/@total – Total transcriptions contributed over all time.translations/@total – Total translations contributed over all time.Adding “fullStats=true” to the URL will return the following:@totalMonth – Total contributions made this month.@totalYear – Total contributions made over the previous year.tags/@totalMonth – Total tags created this month.tags/@totalYear – Total tags created this ments/@totalMonth – Total comments (+ replies) contributed over the past ments/@totalYear – Total comments (+ replies) contributed over the past year.transcriptions/@totalMonth – Total transcriptions contributed in the past month.transcriptions/@totalYear – Total transcriptions contributed in the past year.translations/@totalMonth – Total translations contributed over the past month.translations/@totalYear – Total translations contributed over the past year.XML Example (simple counts)GET DisplayFullNameFlag="true" isNaraStaff="true" total="74" userFullName="Thomas Jefferson"> <tags total="27"/> <transcriptions total="27"/> <comments total="10"/> <translations total="10"/> </contributions>JSON Example (simple counts)GET"contributions":{ "@userFullName":"Thomas Jefferson", "@DisplayFullNameFlag":"true", "@isNaraStaff":"true", "@total":"74", "tags":{ "@total":"27" }, "transcriptions":{ "@total":"27" }, "comments":{ "@total":"10" }, "translations” :{ "@total”:”10” } }XML Example (full statistics)GET DisplayFullNameFlag="true" isNaraStaff="true" total="74" totalMonth="26" totalYear="74" userFullName="Thomas Jefferson"> <tags total="27" totalMonth="14" totalYear="27"/> <transcriptions total="27" totalMonth="10" totalYear="27"/> <comments total="10" totalMonth="1" totalYear="10"/> <translations total="10" totalMonth="1" totalYear="10"/> </contributions>JSON Example (full statistics)GET"contributions":{ "@userFullName":"Thomas Jefferson", "@DisplayFullNameFlag":"true", "@isNaraStaff":"true", "@total":"74", "@totalMonth":"26", "@totalYear":"74", "tags":{ "@total":"27", "@totalMonth":"14", "@totalYear":"27" }, "transcriptions":{ "@total":"27", "@totalMonth":"10", "@totalYear":"27" }, "comments":{ "@total":"10", "@totalMonth":"1", "@totalYear":"10" }, "translations":{ "@total":"10", "@totalMonth":"1", "@totalYear":"10" }} Common Parameters for ContributionsAll of the user contribution methods support several common parameters for paging and sorting.ParameterDescriptionExamplesoffset=#The zero-based offset into the list of the first result to be returned. This parameter is used in combination with ‘rows’ to paginate the list. If missing, the default offset is 0.If an offset less than 0 or greater than the total is specified, an error is returned.offset=100 rows=#Indicates the number of entries in the list to fetch. The default is 25.The maximum value for rows is 200. [TBD]rows=50sort=field [asc|desc]Sorts listing based on a field value. Specify the field to sort by followed by “asc” for ascending or “desc” for descending. The current fields are defined:lastModified – [all annotations] The date the annotation was last modified.tag – [tag list only] The text of the tag.count – [tag list only] The number of occurrences of the tag.sort=lastModified asc Error CodesIf the paging parameters are incorrect, then a standard error header will be returned (see section REF _Ref379726032 \r \h 1.5.2) with one of the following error codes:Error CodeDescriptionParametersINVALID_OFFSETAn incorrect offset was requested.offset: The requested offset.avail: The number of rows available.INVALID_ROWSA “rows” number less than zero was requested.rows: The requested rows.TOO_MANY_ROWSToo many rows were requested.rows: The requested rows.max: The maximum number of rows allowed.INVALID_SORTInvalid sort field or sort direction requested.noneUser Contributed CommentsUser contributed comments can be fetched using the following URL:GET URL will accept the common parameters specified above in section REF _Ref380661158 \r \h 5.2.2.ResponseWhen the listing of entities (digital objects, authority records, and descriptions) annotated by comments for a particular user are requested, the following information is returned.total – Total count of all comments made by the ments/comment/@id – The ID for this comment.Uniquely identifies this ID within Catalog. Can be used to perma-link the ments/comment/@lastModified – Date this comment was last modified, or created (if no modifications have been made).comments/comment/@replies – The number of replies for this comment. comments/comment/@title – A display title for the contribution. Usually the title of the associated description or authority record.For archival descriptions: (all contained within the <comments/comment> tag)naId – The NAID of the description on which the comment was made.For digital objects:naId – The NAID of the description which contains the object.objectId – The object ID on which the comment was made.pageNum – The page number for the object.totalPages – Total of pages for this description.For person authority records:naId – The person ID number.For organization authority records:naId – The organization ID number. XML ExampleGET; <total>3</total> <comment id="9012" lastModified="2015-06-29T16:54:50.000Z" parentId="0" replies="0" title="[Scotland - Dundee - Consulate] Register of Correspondence Received and Sent"> <naId>1307945</naId> <totalPages>0</totalPages> <pageNum>0</pageNum> </comment> <comment id="9222" lastModified="2015-06-29T16:54:15.000Z" parentId="0" replies="2" title="Fall 1981: 8-91-1 An Interview with Richard Helms, by David Frost"> <naId>7283099</naId> <totalPages>31</totalPages> <pageNum>31</pageNum> </comment> <comment id="8889" lastModified="2015-06-29T16:53:40.000Z" parentId="0" replies="1" title="Spring 1981: 7-89-4: Harry S. Truman on CIA Covert Operations, by Hayden B. Peake"> <naId>7283080</naId> <objectId>15692924</objectId> <totalPages>12</totalPages> <pageNum>2</pageNum> </comment> </comments>JSON ExampleGET"comments":{ "total":3, "comment":[ { "@id":"9012", "@parentId":"0", "@title":"[Scotland - Dundee - Consulate] Register of Correspondence Received and Sent", "naId":"1307945", "totalPages":0, "pageNum":0, "@replies":"0", "@lastModified":"2015-06-29T16:54:50.000Z" }, { "@id":"9222", "@parentId":"0", "@title":"Fall 1981: 8-91-1 An Interview with Richard Helms, by David Frost", "naId":"7283099", "totalPages":31, "pageNum":31, "@replies":"2", "@lastModified":"2015-06-29T16:54:15.000Z" }, { "@id":"8889", "@parentId":"0", "@title":"Spring 1981: 7-89-4: Harry S. Truman on CIA Covert Operations, by Hayden B. Peake", "naId":"7283080", "objectId":"15692924", "totalPages":12, "pageNum":2, "@replies":"1", "@lastModified":"2015-06-29T16:53:40.000Z" } ] }User Contributed TagsFetching all unique tagsThe list of all unique contributed tags can be fetched using the following URL:GET URL will accept the common parameters specified above in section REF _Ref380661158 \r \h 5.2.2.SortingThe list of all unique tags for the user can be sorted by:sort=tagSort by the tag text.sort=countSort by the number of times the user has contributed the tag.Default sort is by tag text.ResponseWhen the listing of tags created by a user is requested, the following information is returned.tags/total – Total count of all tags made by the user..tags/tag/count – The number of entities tagged with this tag.tags/tag/tag – The actual text of the tag.XML ExampleGET; <total>2</total> <tag> <count>6</count> <tag>Cuba</tag> </tag> <tag> <count>3</count> <tag>Bay of Pigs</tag> </tag> </tags>JSON ExampleGET"tags":{ "total":2, "tag":[ { "count":6, "tag":"Cuba" }, { "count":3, "tag":"Bay of Pigs" } ] }Fetching all contributions for a contributed tagTo fetch the list of contributions for a single contributed tag, use:GET contributions/tags/titles?tagtext=<tag>&username=<user-name>The URL will accept the common parameters specified above in section REF _Ref380661158 \r \h 5.2.2.ResponseWhen the listing of entities (digital objects, authority records, and descriptions) annotated by comments for a particular user are requested, the following information is returned.titles/total – Total count of all contributions made by the user for the tag.titles/title/addedTs – The date the tag was placed.titles/title/opaTitle – A display title for the contribution. Usually the title of the associated description or authority record.titles/title/naId – The NAID of the description on which the comment was made.For digital objects:titles/title/objectId – The object ID on which the tag was placed.titles/title/pageNum– A display value which helps identify the object to the user. Typically a page number. XML ExampleGET; <title> <element> <addedTs>2015-06-29T19:59:57.000Z</addedTs> <naId>6920522</naId> <opaTitle>Cuba</opaTitle> <opaType>itemAv</opaType> <pageNum>0</pageNum> <totalPages>0</totalPages> </element> <element> <addedTs>2015-06-29T19:59:54.000Z</addedTs> <naId>7412730</naId> <opaTitle>633) Bay of Pigs</opaTitle> <opaType>fileUnit</opaType> <pageNum>0</pageNum> <totalPages>0</totalPages> </element> <element> <addedTs>2015-06-29T19:59:51.000Z</addedTs> <naId>7284003</naId> <objectId>15744634</objectId> <opaTitle>Winter 1979: 19-58-4: Book Reviews: Bay of Pigs, by Peter Wyden</opaTitle> <opaType>fileUnit</opaType> <pageNum>1</pageNum> <totalPages>4</totalPages> </element> </title> <total>3</total> </titles>JSON ExampleGET"titles":{ "total":3, "title":[ { "naId":"6920522", "opaTitle":"Cuba", "opaType":"itemAv", "pageNum":"0", "totalPages":"0", "addedTs":"2015-06-29T19:59:57.000Z" }, { "naId":"7412730", "opaTitle":"633) Bay of Pigs", "opaType":"fileUnit", "pageNum":"0", "totalPages":"0", "addedTs":"2015-06-29T19:59:54.000Z" }, { "naId":"7284003", "opaTitle":"Winter 1979: 19-58-4: Book Reviews: Bay of Pigs, by Peter Wyden", "opaType":"fileUnit", "objectId":"15744634", "pageNum":"1", "totalPages":"4", "addedTs":"2015-06-29T19:59:51.000Z" } ] } User Contributed TranscriptionsAll user contributed transcriptions can be accessed through the following URL:GET URL will accept the common parameters specified above in section REF _Ref380661158 \r \h 5.2.2.ResponseWhen the listing of digital objects that have transcriptions by a particular user is requested, the following information is returned.titles/total – Total count of all transcriptions made by the user.titles/title – Information on a transcription contributed by the user.titles/title/LastModifiedByUserTs – Date the transcription was last modified by or created (if no modifications have been made) the user.titles/title/versionAddedTs – Date the transcription was last modified by someone else.Attribute may be missing of no one else has modified the transcription, or if the user was the last one to modify the transcription.titles/title/ModifiedBy – The user ID of the other user who transcribed the object.titles/title/ModifiedByDisplayName – The full name or username of the other user.titles/title/opaTitle – A display title for the contribution. Usually the title of the associated description.titles/title/naId – The NAID of the description on which the transcription was made.For digital objects:titles/title/objectId – The object ID on which the transcription was made.titles/title/pageNum – A display value which helps identify the object to the user. Typically a page number.XML ExampleGET; <total>1</total> <title> <naId>2668751</naId> <opaTitle>Truman Doctrine</opaTitle> <opaType>item</opaType> <objectId>14293115</objectId> <pageNum>1</pageNum> <totalPages>3</totalPages> <versionAddedTs>2015-06-29T20:55:36.000Z</versionAddedTs> <createdTs>2015-02-03T19:43:52.000Z</createdTs> <LastModifiedByUserTs>2015-06-29T20:47:44.000Z</LastModifiedByUserTs> <UserDisplayName>Mary Stewart</UserDisplayName> <LastModifiedByOtherTs>2015-06-29T20:55:36.000Z</LastModifiedByOtherTs> <ModifiedBy>tjefferson</ModifiedBy> <ModifiedByDisplayName>Thomas Jefferson</ModifiedByDisplayName> <CreatedBy>tjefferson</CreatedBy> <CreatedByDisplayName>Thomas Jefferson</CreatedByDisplayName> </title></titles>JSON ExampleGET"titles":{ "total":1, "title":[ { "naId":"2668751", "opaTitle":"Truman Doctrine", "opaType":"item", "objectId":"14293115", "pageNum":"1", "totalPages":"3", "versionAddedTs":"2015-06-29T20:55:36.000Z", "createdTs":"2015-02-03T19:43:52.000Z", "LastModifiedByUserTs":"2015-06-29T20:47:44.000Z", "UserDisplayName":"Mary Stewart", "LastModifiedByOtherTs":"2015-06-29T20:55:36.000Z", "ModifiedBy":"tjefferson", "ModifiedByDisplayName":"Thomas Jefferson", "CreatedBy":"tjefferson", "CreatedByDisplayName":"Thomas Jefferson" } ] }User Contributed TranslationsAll user contributed translations can be accessed through the following URL:GET URL will accept the common parameters specified above in section REF _Ref380661158 \r \h 5.2.2.ResponseWhen the listing of digital objects that have translations by a particular user is requested, the following information is returned.translations/total – Total count of all translations made by the user.translations/translation – Information on a translation contributed by the user.translations/translation/LastModifiedByUserTs – Date the translation was last modified by or created (if no modifications have been made) the user.translations/translation/versionAddedTs – Date the translation was last modified by someone else.Attribute may be missing of no one else has modified the translation, or if the user was the last one to modify the translation.translations/translation/ModifiedBy – The user ID of the other user who translated the object.translations/translation/ModifiedByDisplayName – The full name or username of the other user.translations/translation/opaTitle – A display title for the contribution. Usually the title of the associated description.translations/translation/naId – The NAID of the description on which the translation was made.translations/translation/objectId – The object ID on which the translation was made.translations/translation/pageNum – A display value which helps identify the object to the user. Typically a page number.translations/translation/language – The full English name for the language.translations/translation /languageCode – The ISO 639-3 3-letter code for the language.XML ExampleGET; <total>1</total> <translation> <naId>2668751</naId> <opaTitle>Truman Doctrine</opaTitle> <opaType>item</opaType> <objectId>14293115</objectId> <pageNum>1</pageNum> <totalPages>3</totalPages> <language>Spanish</language> <languageCode>SPA</languageCode> <versionAddedTs>2015-06-29T20:55:36.000Z</versionAddedTs> <createdTs>2015-02-03T19:43:52.000Z</createdTs> <LastModifiedByUserTs>2015-06-29T20:47:44.000Z</LastModifiedByUserTs> <UserDisplayName>Mary Stewart</UserDisplayName> <LastModifiedByOtherTs>2015-06-29T20:55:36.000Z</LastModifiedByOtherTs> <ModifiedBy>tjefferson</ModifiedBy> <ModifiedByDisplayName>Thomas Jefferson</ModifiedByDisplayName> <CreatedBy>tjefferson</CreatedBy> <CreatedByDisplayName>Thomas Jefferson</CreatedByDisplayName> </translation></translations>JSON ExampleGET"translations":{ "total":1, "translation":[ { "naId":"2668751", "opaTitle":"Truman Doctrine", "opaType":"item", "objectId":"14293115", "pageNum":"1", "totalPages":"3", "language":"Spanish", "languageCode":"SPA", "versionAddedTs":"2015-06-29T20:55:36.000Z", "createdTs":"2015-02-03T19:43:52.000Z", "LastModifiedByUserTs":"2015-06-29T20:47:44.000Z", "UserDisplayName":"Mary Stewart", "LastModifiedByOtherTs":"2015-06-29T20:55:36.000Z", "ModifiedBy":"tjefferson", "ModifiedByDisplayName":"Thomas Jefferson", "CreatedBy":"tjefferson", "CreatedByDisplayName":"Thomas Jefferson" } ] }My ListsUsers can manage their saved search results lists from their account. They can rename and delete lists, delete all lists, and delete specific entries from a list. Note that creating a new list and adding results to a list occurs as part of a rmation about a user’s lists can be accessed using the following URLs:GET a list of all lists for a specific userGET information for a specific listNote:Lists are only available when logged in (see section REF _Ref379794618 \r \h 1.6).Except share lists which have their persistent url.The logged in user can only fetch lists for themselves (not for others)Managing the List of ListsFetching the Lists of ListsThe following URL can be used to fetch the list of all of the user’s saved lists:GET that all lists are always retrieved. There is no pagination of the list of lists.ResponseThe following attributes are provided for the list of the user’s lists:userLists/total – The total number of lists the user has.userLists/userList/@name – The list name. This information is repeated for each of the user’s lists.userLists/userList/total – The total number of results in the list.userLists/userList/@created – The date time the list was created.userLists/userList/@lastModified – The date time the list was last modified.The following examples show how to obtain summary information about all lists for a specific user. XML ExampleGET; <total>2</total> <userList name="Truman Info" total="66" lastModified="2015-06-29 21:52:16.0" created="2015-06-29 21:52:16.0"/> <userList name="Kennedy search" total="150" lastModified="2015-06-29 21:52:16.0" created="2015-06-29 21:52:16.0"/></userLists>JSON ExampleGET"userLists":{ "total":2, "userList":[ { "@name":"Truman Info", "total":66, "@lastModified":"2015-06-29 21:52:16.0", "@created":"2015-06-29 21:52:16.0" }, { "@name":"Kennedy search", "total":150, "@lastModified":"2015-06-29 21:52:16.0", "@created":"2015-06-29 21:52:16.0" } ] }Modifying the List of ListsThe list of lists can be modified. Single actions are provided to delete all lists or create a new, empty list.To delete all lists:DELETE create a new list:POST the name of the list.In this context, only used when action=create.listname=listnameExamplesDelete all lists:DELETE a new list called “Hello World”:POST response will the standard Catalog response (see section REF _Ref379726032 \r \h 1.5.2 for more information).Error CodesCreating a new list could return the following error code:Error CodeDescriptionParametersDUPLICATE_LISTThe list name specified already exists.list: The list name requested.NOT_LOGGED_INAttempted to modify a list when not logged in.noneNOT_OWNERAttempted to modify someone else’s list.request: The user ID attempting to modify the list.Managing a Single ListSingle lists can be renamed and deleted. This is done with the following URLs:Rename a list:PUT a list:DELETE the name for the listlistname=Truman%20Listnewname=newListNameSpecifies the new name for the list, when action=renamenewName=Truman%20InfoExamplesDelete the “Truman Old” list:DELETE the list “Truman Old” to “Truman New” in the “mstewart” account:PUT response will the standard Catalog response (see section REF _Ref379726032 \r \h 1.5.2 for more information).Error CodesCreating a new list could return the following error code:Error CodeDescriptionParametersDUPLICATE_LISTThe list name specified already exists.list: The list name requested.NOT_LOGGED_INAttempted to modify a list when not logged in.noneNOT_OWNERAttempted to modify someone else’s list.request: The user ID attempting to modify the list.Creating or Adding to a List using the Search APILists can be created and built using the search API, with the following URLs:To save search results to a new list:POST . . &list=<list-name>To add results to an existing list:POST . . &list=<list-name>ExamplesSave the first 10 descriptions which mention the word “truman” to a new list called “HTList”:POST results 11-20 to “HTList”:POST response will the standard Catalog response (see section REF _Ref379726032 \r \h 1.5.2 for more information).Error CodesCreating a new list could return the following error code:Error CodeDescriptionParametersDUPLICATE_LISTThe list name specified already exists.list: The list name requested.MISSING_LISTThe “list” parameter is missing when action=addList or action=newList.noneINVALID_LISTAn invalid list name was specified when saving results to a list with action=addList.list: The list name requested.NOT_LOGGED_INAttempted to modify a list when not logged in.noneNOT_OWNERAttempted to modify someone else’s list.request: The user ID attempting to modify the list.Managing List ResultsThis section covers the methods for fetching the results from a saved list and manipulating those results (creating, adding).Fetching List ResultsFetching information from a saved list shares some of the same parameters as for performing a standard search with the Search API (section REF _Ref379443499 \r \h 3). Fetching list results is done with the following URL:GET . . .ParametersParameterDescriptionExamplesControlling the OutputresultFields=field1, field2,field3, . . .List of fields to return for results from the list.If a field is given that cannot be put in the return (such as a field that does not exist), an error is returned.If no fields are specified, the following fields are returned automatically: naId, opaId, url, localId, hmsEntryNumbers, containerId, iconType, title, titleDate, parentLevel, parentTitle, creators, thumbnailFile.If “*” is specified, then all standard fields are returned except “content” and the XML fields specified in section REF _Ref379710490 \r \h 3.4.7. Those fields would need to be specified individually, and limits may be placed on their use [future, TBD].resultFields=title, urlresultFields=*, descriptionoffset=#The zero-based offset into the list of the first result to be returned. This parameter is used in combination with ‘rows’ to paginate the results. If missing, the default offset is 0.If an offset less than 0 or greater than the maximum [Maximum TBD – based on type of user] is specified, an error is returned.offset=100 rows=#Indicates the number of results to fetch from the list. The default is 25.The maximum value for rows is 200. [TBD]rows=50ResponseThe following is a general outline of what is returned when fetching results from a list:<results total="--total-matching-results --" offset="--first-result-num--" rows="-- num-results--"> <result num="--result-number--"> <FIELD-NAME1>FIELD-VALUE1</FIELD-NAME1> <FIELD-NAME2>FIELD-VALUE2</FIELD-NAME2> <FIELD-NAME3>FIELD-VALUE3</FIELD-NAME3> . . MORE FIELDS GO HERE . </result> . . MORE RESULTS GO HERE .</results>In the above outline, the various values are:@total – The total number of results across all of Catalog which match the query. This number may be thousands or millions large.@offset – The offset number of the first result returned.rows – The actual number of results returned.result – Holds the selected metadata returned for each result.result/@num – The result number (where 0 is the first result) within the list of all possible results (not just results returned by this query).XML ExampleGET total="6695" offset="0”> <rows>25</rows> <result num="0"> <naId>7226539</naId> <opaId>desc-7226539</opaId> <title>Letter from George McGovern to Harry S. Truman</title> <parentTitle>Subject Files, 1953 - 1972</parentTitle> <titleDate>1972-08-19</titleDate> <url>; <localId>hst-ppp_93-1_18</localId> <iconType>nara/item</iconType> <creators><val>Truman, Harry S., 1884-1972</val></creators> <thumbnailFile>hst-ppp_93-1_18-01.jpg</thumbnailFile> </result> <result num="1"> <naId>7283002</naId> <opaId>desc-7283002</opaId> <title>Spring 1976: 7-69-1: Truman on CIA (Examining President Truman's Role in the Establishment of the Agency), by Thomas F. Troy</title> <parentTitle>Articles from "Studies in Intelligence", 1955 - 1992</parentTitle> <parentLevel>series</parentLevel> <url>; <hmsEntryNumbers><val>A1 27</val></hmsEntryNumbers> <iconType>nara/fileUnit</iconType> <creators><val>Central Intelligence Agency. (12/04/1981 - )</val></creators> <thumbnailFile>263-a1-27-box-7-69-1-0001.jpg</thumbnailFile> </result> . . MORE RESULTS GO HERE .</results>JSON ExampleGET lists/viewentries/Truman%20Misc?offset=0&format=json"results":{ "@total":"6695", "@offset":"0", "rows":"25", "result":[ { "@num":"0", "naId":"7226539", "opaId":"desc-7226539", "title":"Letter from George McGovern to Harry S. Truman", "parentTitle":"Subject Files, 1953 - 1972", "titleDate":"1972-08-19", "url":"", "localId":"hst-ppp_93-1_18", "iconType":"nara/item", "creators":["Truman, Harry S., 1884-1972"], "thumbnailFile":"hst-ppp_93-1_18-01.jpg" }, { "@num":"1", "naId":"7283002", "opaId":"desc-7283002", "title":"Spring 1976: 7-69-1: Truman on CIA (Examining President Truman's Role in the Establishment of the Agency), by Thomas F. Troy", "parentTitle":"Articles from \"Studies in Intelligence\", 1955 - 1992", "parentLevel":"series", "url":"", "hmsEntryNumbers":["A1 27"], "iconType":"nara/fileUnit", "creators":["Central Intelligence Agency. (12/04/1981 - )"], "thumbnailFile":"263-a1-27-box-7-69-1-0001.jpg" } . . MORE RESULTS GO HERE . ]}Error CodesThe following error codes are currently defined when fetching the contents of a list:Error CodeDescriptionParametersEMBEDDED_HTMLThe query or filter parameters contain embedded HTML which implies a potential cross-site scripting attack.param: The parameter where the embedded HTML was detected.INVALID_PARAM_VALUEThe value specified to a parameter was invalid. For example, an incorrect source value, incorrect group type, etc.param: The parameter which contained the invalid value.INVALID_FIELDA request was made to search over an invalid field.param: The parameter which contained the invalid field.field: The invalid field name.OFFSET_LIMIT_EXCEEDEDThe maximum search result request has exceeded the limit. See the “offset” parameter for more details.request: The result number requested.max: The maximum result number allowed.ROWS_LIMIT_EXCEEDEDThe maximum number of rows to be returned with the search results was reached.request: The number of rows requested.max: The maximum number of rows allowed.NOT_LOGGED_INAttempted to modify a list when not logged in.noneNOT_OWNERAttempted to modify someone else’s list.request: The user ID attempting to modify the list.Exporting List ResultsResults in a list can be exported in a variety of different formats (PDF, HTML, etc) with different types of metadata. See section REF _Ref380957862 \r \h 3.6 for all export parameters.Use the list URL to export list results:GET parameters ...For example the following call will export brief results for the first 1000 records in the list as PDF with embedded thumbnails:GET List ResultsThe contents of a list can be modified by individually adding or deleting entries from the list using the following URLs:Deleting all list entries:DELETE a list entry:DELETE a list entry:POST what type of item to add to the search results.opaId – Add results based on OPA-ID valuesdescription – an archival descriptionperson – a person authority recordorganization – an organization authority recordobject – a digital objectwebPage – a web page from or a presidential librarywhat=descriptionwhat=objectFor use when what=opaIdopaIds=ID-valueSpecify the OPA-ID to add or delete from the list. See section REF _Ref380704093 \r \h 1.4.2 for OPA-ID formats.Can be a comma separated list of OPA-ID values.opaIds=desc-7228234opaIds=desc-7228234,person-2223For use when what=description or objectnaid=ID-valueSpecify the NAID value of the new entry to add to or delete from the list.naid=7228234For use when what=objectobjectId=Object IDSpecify the object ID of the object to add or delete the digital object from the list.Note: Also requires a naid parameter.objectId=93For use when what=person or organizationauthId=ID-valueEither the person ID or the organization ID of the authority record to add or delete from the list.authId=8889For use when what=webpageurl=web-page-urlThe URL of the web page to add or delete from the list.url= the entry with OPA-ID “desc-7228924” from mstewart’s “Truman Presidency” list:DELETE the description 7228924 to mstewart’s “Truman Presidency” list:POST three OPA-ID’s to mstewart’s “Truman Presidency” list:POST response will the standard OPA response (see section REF _Ref379726032 \r \h 1.5.2 for more information).Error CodesThe following error codes are currently defined as part of the Search API response:Error CodeDescriptionParametersMISSING_PARAMA necessary parameter is missing. Either the “what” parameter, or one of the other parameters necessary to identify the entry to delete or add.param: The parameter which is missing.UNKNOWN_WHATThe value specified for the “what” parameter is not one of the allowed values.what: The value of the what parameter specified.DELETE_ENTRY_NOT_IN_LISTThe item requested to be deleted is not currently in the list.The following params specify what was requested:what: The type of itemopaId: The OPA-IDnaid: The NAIDobjectId: The object IDauthId: The person or org IDurl: The web page URLADD_ENTRY_NOT_IN_OPAThe item requested to be added to the list is not found in the Catalog search engine index.All items added to the list must be in the search engine index.The following params specify what was requested:what: The type of itemopaId: The OPA-IDnaid: The NAIDobjectId: The object IDauthId: The person or org IDurl: The web page URLNOT_LOGGED_INAttempted to modify a list when not logged in.noneNOT_OWNERAttempted to modify someone else’s list.request: The user ID attempting to modify the list.Bulk ExportsInformation about bulk downloads for a user can be obtained using the Catalog APIs. Information about bulk downloads can be accessed using the following URLs:Fetch a list of all available or in-progress bulk exports for a specific user:GET information on a specific bulk export:GET a single bulk export file:GET exports are only available when logged in.The logged in user can only fetch the bulk exports for themselves (not for others).However, the download file is available to anyone.Fetching the List of Bulk ExportsUse the following URL to fetch a list of bulk exports for the specified user:GET the download output, the following attributes are provided for each bulk export:accountExports/@total – Total of bulk exports requested by this user.accountExports/accountExport – Contains information on each bulk export.accountExports/accountExport/exportId – The ID number for this bulk export. This will be the same ID number reported when the bulk export was first created.accountExports/accountExport/exportName– A computer generated description about the bulk export from the query used to generate the items.accountExports/accountExport/status– The current status of the bulk export. It could be “Queued”, “Scheduled”, “Processing”, “Completed”.accountExports/accountExport/percentageComplete – The percentage complete. An integer from 1 to 100.accountExports/accountExport/totalProcesedRecords – The total count of everything processed to be included in the download.For bulk exports from searches, this will be the number of search results.accountExports/accountExport/exportFormat – The search results format requested for the bulk-export.accountExports/accountExport/requestTs – The date-time the request was made and the bulk-export was queued.accountExports/accountExport/expiresTs – The date-time when the export file will be removed from the system.accountExports/accountExport/downloadUrl – The URL where the export file can be downloaded.XML ExampleGET total=1> <accountExport> <exportId>1396</exportId> <exportName>tjefferson - 2015-06-30T14:49:40.413Z - 1396</exportName> <status>Completed</status> <exportFormat>PDF</exportFormat> <requestTs>2015-06-30T14:49:40.000Z</requestTs> <expiresTs>2015-08-29T14:49:40.000Z</expiresTs> <downloadUrl>/OpaAPI/iapi/v1/exports/auth/files/1396</downloadUrl> <percentageComplete>100</percentageComplete> <bulkExport>true</bulkExport> <fileSize>5790688</fileSize> <totalProcesedRecords>25000</totalProcesedRecords> </accountExport></accountExports>JSON ExampleGET"accountExports":{ "@total":"1", "accountExport":[ { "exportId":1396, "exportName":"tjefferson - 2015-06-30T14:49:40.413Z - 1396", "status":"Completed", "exportFormat":"PDF", "requestTs":"2015-06-30T14:49:40.000Z", "expiresTs":"2015-08-29T14:49:40.000Z", "downloadUrl":"\/OpaAPI\/iapi\/v1\/exports\/auth\/files\/1396", "percentageComplete":100, "bulkExport":true, "fileSize":5790688, "totalProcesedRecords":25000 } ] }Downloading a Bulk Export FileOnce the download is complete, the download file will be returned in the bulk exports list. The file name will be based on the download ID:GET example:GET a Bulk Export Users may cancel (or delete) a bulk export from the list. This is done with the following URL:DELETE a bulk export:DELETE response will the standard Catalog response (see section REF _Ref379726032 \r \h 1.5.2 for more information).Error CodesThe following error codes are currently defined as part of the API response:Error CodeDescriptionParametersNO_BULK_EXPORTAn invalid or non-existing bulk export identifier was used in the delete request.id: The identifier used in the request.NOT_LOGGED_INThis will be returned for users who attempt to create or edit a translation without logging in.noneNOT_OWNERThis will be returned if trying to delete a bulk download or viewing the list of bulk downloads for another user account.request: The user ID who requested to edit the authoritative translation.NotificationsEvents which may be of interest to the user will be included in the user’s notifications. Currently, this includes:Modifications to any of the user’s transcriptions or translationsDeletion of any of the user’s annotations by a moderatorReplies to the user’s commentNotifications can be accessed through the following URL:GET are only available when logged in.The logged in user can only fetch the notifications for themselves (not for others).ParametersThe following parameters are supported for fetching or clearing notifications:ParameterDescriptionExamplesoffset=#The zero-based offset into the list notifications to be returned. This parameter is used in combination with ‘rows’ to paginate the list. If missing, the default offset is 0.If an offset less than 0 or greater than the total is specified, an error is returned.offset=100 rows=#Indicates the number of notifications to fetch. The default is 25.The maximum value for rows is 200. [TBD]rows=50ResponseWhen fetching notifications, the following data will be returned:notification – Detailed information on an individual notification, with the following sub-elements:@on – Specifies what was transcribed, one of “description”, “object”, “person”, or “organization”.title – A display title for the contribution associated with the event. Usually the title of the associated description or authority record.description – Detailed information on the description associated with the notification, with the following sub-elements:@naid – The NAID of the description on which the comment was made.@objectId – The object ID on which the comment was made.@pageNum – A display value which helps identify the object to the user. Typically a page number.event – The event which created the notification, with the following sub-elements:@type – The type of event. One of: “edit”, “delete”, or “reply”.@on – Specifies the type of annotation associated with the event. Can be one of “tag”, “transcription”, “translation”, or “comment”.@when – Date-time which the event occurred.@otherUser – The user ID of the other user who initiated the event.@otherFullName – The full name of the other user.@otherIsNaraStaff – “true” if the other user is a NARA staff ment – Details on the comment associated with the event (if on=”comment”). Contains the following sub-element:@id – The comment ID. Can be used to permalink to the comment.XML ExampleGET; <total>1</total> <totalNew>1</totalNew> <notification on="item"> <event type="UPDATE" on="transcriptions" when="2015-06-29T20:55:36.000Z" otherUser="kmartin" otherFullName="Kristy Martin" isNaraStaff=”false” displayNameFlag=”false”> </event> <title>Truman Doctrine</title> <item naId="2668751" objectId="14293115" pageNum=1 totalPages=3> </item> </notification></notifications>JSON ExampleGET"notifications":{ "total":1, "totalNew":1, "notification":[ { "@on":"item", "event":{ "@type":"UPDATE", "@on":"transcriptions", "@when":"2015-06-29T20:55:36.000Z", "@otherUser":"kmartin", "@otherFullName":"Kristy Martin", "@isNaraStaff":"false", "@displayNameFlag":"false" }, "title":"Truman Doctrine", "item":{ "@naId":"2668751", "@objectId":"14293115", "@pageNum":"1", "@totalPages":"3" } } ] }Clearing NotificationsNotifications can be cleared using the following URL:DELETE example:DELETE must be logged in to change notifications.Users can only clear their own notifications.ResponseThe response will the standard Catalog response (see section REF _Ref379726032 \r \h 1.5.2 for more information).Error CodesIf the paging parameters are incorrect, then a standard error header will be returned (see section REF _Ref379726032 \r \h 1.5.2) with one of the following error codes:Error CodeDescriptionParametersINVALID_OFFSETAn incorrect offset was requested.offset: The requested offset.avail: The number of rows available.INVALID_ROWSA “rows” number less than zero was requested.rows: The requested rows.TOO_MANY_ROWSToo many rows were requested.rows: The requested rows.max: The maximum number of rows allowed.NOT_LOGGED_INThis will be returned for users who attempt to clear or view notifications without logging in.noneNOT_OWNERThis will be returned if trying clear or view someone else’s notifications.request: The user ID who requested to edit the authoritative translation.Account InformationThe Catalog User APIs can be used to change account information such as the user’s full name, e-mail address, active account status, etc.Viewing Account InformationUse the following URL to view the user’s account information:GET must be logged into to view account information (see section REF _Ref379794618 \r \h 1.6).Users can only view their own account information.XML ExampleGET; <userId>tjefferson</userId> <userType>registeredUser</userType> <fullName>Thomas Jefferson</fullName> <isFullNamePublic>true</isFullNamePublic> <email>thomas.jefferson@</email></account>JSON ExampleGET{ "userId":"tjefferson", "userType":"registeredUser", "fullName":"Thomas Jefferson", "isFullNamePublic":"true", "email":"thomas.jefferson@"}Modifying Account InformationAccount information can be viewed and modified using the following URL:POST (SSL) protocol is absolutely required whenever modifying account information.Standard HTTP requests will be rejected.ParametersParameterDescriptionExamplesaction=change|link|deactivateIndicates what to do with the user’s account information.change – change one or more fields in the user’s account information.Current password is required.link – Link the user to a social media account (Facebook, Twitter, or Google).Current password is required.action=changeaction=linkpassword=passwordThe user’s current password. This must be provided when making any change to the user’s account information.password=abcd1234For use when action=changenewPassword=passwordSpecify the new password. The password must contain a minimum of 8 characters.newPassword=wxyz9876email=emailSpecify the new e-mail address for the user.email=jdoe@fullName=full-nameSpecify the new full name for the user.fullName=Thomas%20JeffersondisplayFullName=true|falseSet to “true” if the full name for the user should be displayed to the public, “false” otherwise.displayFullName=trueFor use when action=link [LOW PRIORITY – RELEASE 2]provider=google|twitterIfacebookThe provider can be any of: “google”, “twitter”, or “facebook”. provider=facebooktoken=token-dataThe token will be the login token returned by the provider’s authentication method.token=82AB20CA238241DF.13289AG8A9EF21090.FEACBA92. . .ExamplesChange the mstewart’s password:POST mstewart’s full name & display full name preference:POST mstewart’s E-mail Address:POST the mstewart account to a google account: [LOW PRIORITY – RELEASE 2]POST. . .ResponseThe response will the standard Catalog response (see section REF _Ref379726032 \r \h 1.5.2 for more information).Error CodesIf the paging parameters are incorrect, then a standard error header will be returned (see section REF _Ref379726032 \r \h 1.5.2) with one of the following error codes:Error CodeDescriptionParametersNOT_LOGGED_INAttempt to view or modify account information without logging in.noneNOT_OWNERAttempt to modify the account information for other users.request: The user ID who made the request.BAD_PROVIDERThe provider name was not one of “google”, “twitter” or “facebook”.noneCORRUPTED_TOKENThe token provided does not appear to be in the expected encoding or format.noneINVALID_TOKENThe token provided for a third-party authentication could not be validated.noneBAD_PASSWORDThe password provided does not match the user’s current password.noneMISSING_PASSWORDAll account modification requests require the user’s current password.noneURL mapping to support selected OPA pilot URLsThe OPA URL mapping API is used to support selected OPA pilot URLs.Mapping legacy URLs to Catalog URLsUse the following URL to map a legacy URL to a new Catalog URL:GET ExampleGET total="2"><naId arcId="3859926" naId="10658335" recordType="topical-subject"/><naId arcId="3859926" naId="10574162" recordType="person"/></naIds>JSON ExampleGET"naIds":{ "@total":"2", "naId":[ { "@arcId":"3859926", "@recordType":"topical-subject", "@naId":"10658335" }, { "@arcId":"3859926", "@recordType":"person", "@naId":"10574162" } ] }ResponseThe response will the standard Catalog response (see section 1.5.2 for more information).Error CodesIf the paging parameters are incorrect, then a standard error header will be returned (see section REF _Ref379726032 \r \h 1.5.2) with one of the following error codes:Error CodeDescriptionParametersNO_URL_MAPPINGS_FOUNDAttempt to map an invalid arcID.noneScheduled maintenance processesA Catalog task scheduler was created in order to execute configured periodic tasks. These tasks are calls to the Catalog API, so API can run some maintenance actions on their side, on a daily basis. Tasks should be specified via the scheduler configuration file where a task can be created with its time to be execute and the endpoint the scheduler needs to call.Here is an XML example used to configure some periodic tasks on the scheduler:<tasks><task name="Clean up unverified accounts"><endpoint>/administrator/accounts/remove-unverified</endpoint><time>14:00:00</time></task><task name="Disable idle accounts"><endpoint>/administrator/accounts/auto-disable</endpoint><time>14:20:00</time></task><task name="Cancel unverified email changes"><endpoint>/administrator/accounts/cancel-email-modifications</endpoint><time>14:40:00</time></task></tasks>Account maintenance processesThe following three tasks are part of the set of periodic maintenance tasks that can be executed on the Catalog task scheduler:Deactivate idle users: An idle account user is a user who hasn’t interacted with the Catalog system for a specific amount of time defined in the API configuration properties. A task was created for deactiving all the idle users whose their last interaction with the system has exceeded the allowed threshold set in the system.Delete unverified accounts: An unverified account user is a user who hasn’t verified his/her registration. Once a user is registered in the system an email with an activation link is sent to the email the user provided while registration, so users can verify their accounts. A task was created for deleting all the accounts who haven’t been verified for a specific period of time set on the API configuration.Delete email change requests: When a user changes his/her email address in Catalog system, an email with a verification link is sent to the new provided email address. Once the user verifies this new email, the email change is done by the API, otherwise no changes occurred on API side. A task was created for deleting all the email change requests which haven’t been verified for the user for a specific period of time set on the API configuration.AppendicesLocation IDsThe following is the list of all location ID values.Location VSearch Value(ref-id)William J. Clinton Library1Dwight D. Eisenhower Library2Franklin D. Roosevelt Library3George Bush Library4Gerald R. Ford Library5Gerald R. Ford Museum6Herbert Hoover Library7Harry S. Truman Library8Jimmy Carter Library9John F. Kennedy Library10Lyndon Baines Johnson Library11Richard Nixon Library - College Park12Ronald Reagan Library13National Archives at Boston14National Archives at New York15National Archives at Philadelphia17National Archives at Atlanta18National Archives at Chicago19National Archives at Kansas City20National Archives at Fort Worth21National Archives at Denver22National Archives at Riverside23National Archives at San Francisco24National Archives at Anchorage25National Archives at Seattle26National Personnel Records Center - Civilian Personnel Records27National Personnel Records Center - Military Personnel Records28National Archives - Washington, DC – Cartographic29National Archives - Washington, DC - Motion Pictures30National Archives - Washington, DC - Still Pictures31National Archives - Washington, DC - Archives I Textual Reference32National Archives - Washington, DC - Archives II Textual Reference (Civilian)33National Archives - Washington, DC – FOIA34National Archives - Washington, DC - Archives II Textual Reference (Military)35Center for Legislative Archives36National Archives - Washington, DC – Electronic37Library of Congress, Prints and Photographs Division (an affiliated archives)38National Park Service, Yellowstone National Park Archives (an affiliated archives)39New Mexico Commission of Public Records, State Records Center and Archives (an affiliated archives)40Oklahoma Historical Society (an affiliated archives)41Pennsylvania Historical and Museum Commission, State Archives (an affiliated archives)42United States Military Academy Archives (an affiliated archives)43United States Naval Academy, William W. Jeffries Memorial Archives (an affiliated archives)44Presidential Materials Division48National Archives at St. Louis50Richard Nixon Library51George W. Bush Library53U.S. Government Printing Office (an affiliated archives)54University of North Texas Libraries (an affiliated archives)57Technical Metadata[Under construction – complete technical metadata provided for all different types of files]Third-Party Authentication [LOW PRIORITY – RELEASE 2][Under construction – exact methods for acquiring the authentication token for all third-party systems: google, twitter, and facebook]Languages[Under construction – ISO 639-3 three letter codes need to be added]List of languages supported by Catalog with the numeric NARA language code and the ISO-639-3 (three-letter) language code.1[ABK] Abkhaz2[ACE] Achinese3[ACH] Acoli4[ADA] Adangme5Afar6Afrihili (Artificial language)7Afrikaans8Afroasiatic (Other)9Akan10Akkadian11Albanian12Aleut13Algonquian (Other)14Aljamma15Altaic (Other)16Amharic17Apache languages18Arabic19Aramaic20Arapaho21Arawak22Armenian23Artificial (Other)24Assamese25Athapascan (Other)26Australian languages27Austronesian (Other)28Avaric29Avestan30Awadhi31Aymara32Azerbaijani33Balinese34Baltic (Other)35Baluchi36Bambara37Bamileke languages38Banda39Bantu (Other)40Basa41Bashkir42Basque43Batak44Beja45Belarusian46Bemba47Bengali48Berber (Other)49Bhojpuri50Bihari51Bikol52Bini53Bislama54Bosnian55Braj56Breton57Bugis58Bulgarian59Buriat60Burmese61Caddo62Carib63Catalan64Caucasian (Other)65Cebuano66Celtic (Other)67Central American Indian (Other)68Chagatai69Chamic languages70Chamorro71Chechen72Cherokee73Cheyenne74Chibcha75Chinese76Chinook jargon77Chipewyan78Choctaw79Church Slavic80Chuvash81Coptic82Cornish83Corsican84Cree85Creek86Creoles and Pidgins (Other)87Creoles and Pidgins, English-based (Other)88Creoles and Pidgins, French-based (Other)89Creoles and Pidgins, Portuguese-based (Other)90Croatian91Cushitic (Other)92Czech93Dakota94Danish95Dayak96Delaware97Dinka98Divehi99Dogri100Dogrib101Dravidian (Other)102Duala103Dutch104Dutch, Middle (ca. 1050-1350)105Dyula106Dzongkha107Efik108Egyptian109Ekajuk110Elamite111English, Middle (1100-1500)112English, Old (ca. 450-1100)113Eskimo languages114Esperanto115Estonian116Ethiopic117Ewe118Ewondo119Fang120Fanti121Faroese122Fijian123Filipino124Finnish125Finno-Ugrian (Other)126Fon127French128French, Middle (ca. 1400-1600)129French, Old (ca. 842-1400)130Frisian131Friulian132Fula133Galician134Ganda135Gayo136Gbaya137Gc138Georgian139German140German, Middle High (ca. 1050-1500)141German, Old High (ca. 750-1050)142Germanic (Other)143Gilbertese144Gondi145Gorontalo146Gothic147Grebo148Greek, Ancient (to 1453)149Greek, Modern (1453- )150Guarani151Gujarati152Gwich'in153Haida154Hausa155Hawaiian156Hebrew157Herero158Hiligaynon159Himachali160Hindi161Hiri Motu162Hittite163Hmong164Hungarian165Hupa166Iban167Icelandic168Igbo169Ijo170Iloko171Indian172Indic (Other)173Indo-European (Other)174Indonesian175Interlingua (International Auxiliary Language Association)176Interlingue177Inuktitut178Inupiaq179Iranian (Other)180Irish181Irish, Middle (ca. 1100-1550)182Irish, Old (to 1100)183Iroquoian (Other)184Italian185Japanese186Javanese187Judeo-Arabic188Judeo-Persian189Kabyle190Kachin191Kalbtdlisut192Kamba193Kannada194Kanuri195Kara-Kalpak196Karen197Kashmiri198Kawi199Kazakh200Khasi201Khmer202Khoisan (Other)203Khotanese204Kikuyu205Kimbundu206Kinyarwanda207Kiswahili208Komi209Kongo210Konkani211Korean212Kpelle213Kru214Kuanyama215Kumyk216Kurdish217Kurukh218Kusaie219Kutenai220Kyrgyz221Ladino222Lahnda223Lakota224Lamba225Lao226Latin227Latvian228Letzeburgesch229Lezgian230Lingala231Lithuanian232Lozi233Luba-Katanga234Luba-Lulua235Luiseqo236Lunda237Luo (Kenya and Tanzania)238Lushai239Macedonian240Madurese241Magahi242Maithili243Makasar244Malagasy245Malay246Malayalam247Maltese248Manchu249Mandar250Mandingo251Manipuri252Manobo languages253Manx254Maori255Mapuche256Marathi257Mari258Marshall259Marwari260Masai261Mayan languages262Mende263Micmac264Minangkabau265Miscellaneous languages266Mohawk267Mohlam268Moldavian269Mon-Khmer (Other)270Mongo-Nkundu271Mongolian272Moori273Multiple languages274Munda (Other)275Nahuatl276Nauru277Navajo278Ndebele (South Africa)279Ndebele (Zimbabwe)280Ndonga281Nepali282Newari283Nias284Niger-Kordofanian (Other)285Nilo-Saharan (Other)286Niuean287North American Indian (Other)288Northern Sami289Northern Sotho290Norwegian291Nubian languages292Nyamwezi293Nyanja294Nyankole295Nyoro296Nzima297Occitan (post-1500)298Ojibwa299Old Norse300Old Persian (ca. 600-400 B.C.)301Oriya302Oromo303Osage304Ossetic305Otomian languages306Pahlavi307Palauan308Pali309Pampanga310Pangasinan311Panjabi312Papiamento313Papuan (Other)314Persian315Philippine (Other)316Phoenician317Polish318Ponape319Portuguese320Prakrit languages321Provengal (to 1500)322Pushto323Quechua324Raeto-Romance325Rajasthani326Rapanui327Rarotongan328Romance (Other)329Romanian330Romany331Rundi332Russian333Salishan languages334Samaritan Aramaic335Sami336Samoan337Sandawe338Sango339Sanskrit340Santali341Sardinian342Sasak343Scots344Scottish Gaelic345Selkup346Semitic (Other)347Serbian348Serer349Shan350Shona351Sidamo352Sign languages353Siksika354Sindhi355Sinhalese356Sino-Tibetan (Other)357Siouan (Other)358Slave359Slavic (Other)360Slovak361Slovenian362Sogdian363Somali364Songhai365Soninke366Sorbian languages367Sotho368South American Indian (Other)369Spanish370Sukuma371Sumerian372Sundanese373Susu374Swahili375Swazi376Swedish377Syriac378Tagalog379Tahitian380Tai (Other)381Tajik382Tamashek383Tamil384Tatar385Telugu386Temne387Terena388Tetum389Thai390Tibetan391Tigri392Tigrinya393Tiv394Tlingit395Tok Pisin396Tokelauan397Tonga (Nyasa)398Tongan399Truk400Tsimshian401Tsonga402Tswana403Tumbuka405 Turkish Ottoman406 Turkmen407 Tuvaluan408 Tuvinian409 Twi410 Ugaritic411 Uighur412 Ukrainian413 Umbundu414 Undetermined415 Urdu416 Uzbek417 Vai418 Venda419 Vietnamese420 Volapjk421 Votic422 Wakashan languages423 Walamo 424 Waray425 Washo426 Welsh427 Wolof428 Xhosa429 Yakut430 Yao431 Yapese432 Yiddish433 Yoruba434 Yupik languages435 Zande436 Zapotec437 Zenaga438 Zhuang439 Zulu440 Zuni ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download