Rest API Commands
The following commands may be given as JSON PUT requests to the SNAC RestFUL API. Most read-only API commands may be called without login, however anything that causes changes in the data require a user object which includes a temporary API key. For examples using the RestFUL API in PHP and Java, view the SNAC RestAPI Examples Repository on GitHub.
Table of Contents
- Discovery
- Reconciliation
- Constellation Views
- Constellation Modifications
- Insert New Constellation
- Insert And Publish New Constellation
- Update Constellation
- Publish Constellation
- Unlock Constellation
- Send Constellation for Review
- Delete Constellation
- Reassign Constellation to Another User
- Add Maybe-Same Constellation Assertions
- Compute Constellation Diff and Set Merge
- Merge Constellations
- Automatically Merge Constellations
- Edit Constellation
- Add external links to a constellation
- Vocabulary Operations
- Resource Operations
- User Operations
API Connection Information
The SNAC RestAPI is available at the following URL.
https://api.snaccooperative.org/
Search Vocabulary
Search through the controlled vocabulary.
Command: |
|
Parameters: |
Term ID, if known. If given a term id, that vocabulary term is directly returned.
Search string to find in the vocabulary list
Type of the vocabulary to search, ex: subject, activity, occupation, geo_place, ...
Entity type ID to filter vocabulary, if known |
Return Values: |
Array of SNAC Term Objects matching the requested query string
SNAC Term Object of the requested term, if term_id was searched
"success" or "failure" depending on whether the query succeeded.
Number of milliseconds spent to produce the result |
Examples: |
Direct Term ReadWhen requesting to find only one term by id, this call returns that exact term, if it exists. Query:{
"command": "vocabulary",
"term_id": 700
}
Response:{
"term": {
"id": "700",
"term": "person",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Person",
"type": "entity_type"
},
"result": "success",
"timing": 9.12
}
Search for TermBeing provided with a query string, the search method returns a list of matching results. Query:{
"command": "vocabulary",
"query_string": "person",
"type": "entity_type",
"entity_type": null
}
Response:{
"results": [
{
"id": "700",
"term": "person",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Person",
"type": "entity_type",
"description": null
}
],
"timing": 10.91
}
|
Read Vocabulary Term
Read a particular controlled vocabulary term.
Command: |
|
Parameters: |
Term ID, if known. If given a term id, that vocabulary term is directly returned.
Type of the vocabulary to search.
The value of the vocabulary to search.
The unique URI of the vocabulary to search. |
Return Values: |
SNAC Term Object of the requested term
"success" or "failure" depending on whether the query succeeded.
Number of milliseconds spent to produce the result |
Examples: |
Read Vocabulary TermWhen requesting to find only one term by id, this call returns that exact term, if it exists. Query:{
"command": "read_vocabulary",
"term_id": 700
}
Response:{
"term": {
"id": "700",
"term": "person",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Person",
"type": "entity_type"
},
"result": "success",
"timing": 9.12
}
Read Geo Vocabulary TermIf type is set to geoPlace, this will read geographic terms. Query:{
"command": "read_vocabulary",
"type": "geoPlace",
"term_id": 2358
}
Response:{
"term": {
"id": "2358",
"uri": "https:\/\/www.geonames.org\/4752031",
"name": "Charlottesville",
"latitude": "38.0293100",
"longitude": "-78.4766800",
"administrationCode": "VA",
"countryCode": "US"
},
"result": "success",
"timing": 141.15
}
|
Reconcile Against SNAC
Reconcile a given constellation against all constellations in SNAC, returning the top results.
Command: |
|
Parameters: |
Constellation object filled with as much information as known about the identity. |
Return Values: |
A list of reconciliation objects, including strength of the match, the Constellation matched, and a vector of individual scores that comprise the match strength.
"success" or "failure" depending on whether the query succeeded.
Number of milliseconds spent to produce the result |
Examples: |
Query:{
"command": "reconcile",
"constellation": {
"dataType": "Constellation",
"entityType": {
"term": "person"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Tubman, Harriet, 1820-1913",
"preferenceScore": 1
}
]
}
}
Response:{
"reconciliation": [
{
"strength": 43.514907186098,
"identity": {
"dataType": "Constellation",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6ms4s8z",
"entityType": {
"term": "person"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Tubman, Harriet, 1820?-1913"
}
],
"id": 17796401
},
"vector": {
"ElasticOriginalNameEntry": 9.020508,
"ElasticNameOnly": 9.020508,
"ElasticSeventyFive": 9.020508,
"MultiStage:ElasticNameOnly:SNACDegree": 13.195286648076,
"EntityTypeFilter": 0,
"OriginalLength": 3.2580965380215
},
"properties": {
"degree": 14
}
},
{
"strength": 14.443286538021,
"identity": {
"dataType": "Constellation",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6pz9nbf",
"entityType": {
"term": "person"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Tubman, Harriet, 1815?-1913."
}
],
"id": 49248679
},
"vector": {
"ElasticOriginalNameEntry": 5.592595,
"ElasticSeventyFive": 5.592595,
"EntityTypeFilter": 0,
"OriginalLength": 3.2580965380215
},
"properties": {
"degree": 1
}
},
{
"...": "..."
}
],
"result": "success",
"timing": 200.33
}
|
Get User Information
Returns the information for the given user, including information for Constellations locked to the user.
Command: |
|
Parameters: |
User object |
Return Values: |
Full user object with name, affiliation Constellation, role and privilege list
List of Group objects to which the user belongs
Unread messages sent to this user
Simplified objects of {id, version, nameEntry} of the Constellations this user has checked out
Simplified objects of {id, version, nameEntry} of the Constellations this user is currently editing (locked)
Simplified objects of {id, version, nameEntry} of the Constellations sent for review to any reviewer
Simplified objects of {id, version, nameEntry} of the Constellations sent for review (locked) to this user
Simplified objects of {id, version, nameEntry} of the Constellations recently published by this user
Number of milliseconds spent to produce the result |
Examples: |
Get Current User InformationQuery:{
"command": "user_information",
"user": {
"...": "..."
}
}
Response:{
"result": "success",
"user": {
"userid": "123456",
"userName": "...",
"firstName": "John",
"lastName": "Smith",
"fullName": "John Smith",
"email": "doctor@example.com",
"active": true,
"affiliation": {
"dataType": "Constellation",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6xq0t7h",
"entityType": {
"id": "698",
"term": "corporateBody",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#CorporateBody",
"type": "entity_type"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "University of Virginia",
"preferenceScore": "99",
"id": "18618207",
"version": "2717174"
}
],
"id": "18614776",
"version": "2717175"
},
"token": {
"access_token": "...",
"expires": 1516245251
},
"roleList": [
{
"privilegeList": [
{
"dataType": "privilege",
"id": "1",
"label": "Edit",
"description": "Edit constellations"
},
{
"...": "..."
}
]
}
],
"groups": [
{
"...": "..."
}
],
"messages": [
{
"...": "..."
}
],
"editing": [
{
"id": "47758348",
"version": "11244077",
"nameEntry": "Feuerbach, Ludwig, 1804-1872"
}
],
"editing_lock": [
{
"id": "50774384",
"version": "11243966",
"nameEntry": "Karr, Gary, 1941-...."
}
],
"review_lock": [
{
"id": "45808987",
"version": "11244000",
"nameEntry": "Koresh, 1838-1908"
}
],
"review": [
{
"...": "..."
}
],
"recent": [
{
"...": "..."
}
],
"timing": 25.678
}
}
|
Insert New Constellation
Insert a new Constellation into SNAC. The Constellation must have the operation flags set to "insert".
Command: |
|
Parameters: |
Valid API Key
Full Constellation object
A commit message |
Return Values: |
Full Constellation object with current id and version numbers
"success" or "failure" depending on whether the query succeeded.
Number of milliseconds spent to produce the result |
Examples: |
Insert a simple ConstellationInserting a Constellation with only one nameEntry Query:{
"command": "insert_constellation",
"apikey": "...",
"constellation": {
"dataType": "Constellation",
"operation": "insert",
"entityType": {
"dataType": "Term",
"id": 700,
"term": "person"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Smith, John (1963-2018)",
"preferenceScore": 99,
"operation": "insert",
"components": [
{
"dataType": "NameComponent",
"text": "Smith, John (1963-2018)",
"operation": "insert",
"order": 0,
"type": {
"id": 400228
}
}
]
}
]
},
"message": "Example insert message."
}
Response:{
"constellation": {
"dataType": "Constellation",
"status": "locked editing",
"entityType": {
"id": 700,
"term": "person"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Smith, John (1963-2018)",
"preferenceScore": 99,
"components": [
{
"dataType": "NameComponent",
"text": "Smith, John (1963-2018)",
"type": {
"id": 400228
},
"id": "76813081",
"version": "11244084",
"operation": "insert"
}
],
"id": "76813080",
"version": "11244084",
"operation": "insert"
}
],
"id": "76813079",
"version": "11244085",
"operation": "insert"
},
"result": "success",
"timing": 686.91
}
|
Insert And Publish New Constellation
Insert a new Constellation into SNAC. The Constellation must have the operation flags set to "insert".
Command: |
|
Parameters: |
Valid API Key
Full Constellation object
A commit message |
Return Values: |
Full Constellation object with current id and version numbers
"success" or "failure" depending on whether the query succeeded.
Number of milliseconds spent to produce the result |
Examples: |
Insert a simple ConstellationInserting a Constellation with only one nameEntry Query:{
"command": "insert_and_publish_constellation",
"apikey": "...",
"constellation": {
"dataType": "Constellation",
"operation": "insert",
"entityType": {
"dataType": "Term",
"id": 700,
"term": "person"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Smith, John (1963-2018)",
"preferenceScore": 99,
"operation": "insert",
"components": [
{
"dataType": "NameComponent",
"text": "Smith, John (1963-2018)",
"operation": "insert",
"order": 0,
"type": {
"id": 400228
}
}
]
}
]
},
"message": "Example insert message."
}
Response:{
"constellation": {
"dataType": "Constellation",
"status": "published",
"entityType": {
"id": 700,
"term": "person"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Smith, John (1963-2018)",
"preferenceScore": 99,
"components": [
{
"dataType": "NameComponent",
"text": "Smith, John (1963-2018)",
"type": {
"id": 400228
},
"id": "76813081",
"version": "11244084",
"operation": "insert"
}
],
"id": "76813080",
"version": "11244084",
"operation": "insert"
}
],
"id": "76813079",
"version": "11244085",
"operation": "insert"
},
"result": "success",
"timing": 686.91
}
|
Update Constellation
Updates SNAC's copy of the given Constellation with this one. Any components with operation flags set to "update" will be overwritten with the new version.
Command: |
|
Parameters: |
Valid API Key
Full Constellation object, with current ids and versions (the result of calling edit)
A commit message |
Return Values: |
Full Constellation object with current id and version numbers
"success" or "failure" depending on whether the query succeeded.
Number of milliseconds spent to produce the result |
Examples: |
Update a simple ConstellationUpdate a Constellation with only one nameEntry Query:{
"command": "update_constellation",
"apikey": "...",
"constellation": {
"dataType": "Constellation",
"id": "76813079",
"version": "11244085",
"entityType": {
"dataType": "Term",
"id": 700,
"term": "person"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Smith, John (Doctor), 1963-2018",
"preferenceScore": 99,
"id": "76813080",
"version": "11244084",
"operation": "update"
}
]
},
"message": "Example update message."
}
Response:{
"constellation": {
"dataType": "Constellation",
"status": "locked editing",
"entityType": {
"id": 700,
"term": "person"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Smith, John (Doctor), 1963-2018",
"preferenceScore": 99,
"id": "76813080",
"version": "11244089",
"operation": "update"
}
],
"id": "76813079",
"version": "11244089"
},
"result": "success",
"timing": 583.96
}
|
Publish Constellation
Publishes the given Constellation in SNAC. This does not make any updates to the Constellation data in SNAC.
Command: |
|
Parameters: |
Valid API Key
Full Constellation object, with current ids and versions (the result of calling edit)
A commit message |
Return Values: |
Full Constellation object with current id and version numbers
"success" or "failure" depending on whether the query succeeded.
Number of milliseconds spent to produce the result |
Examples: |
Publish a ConstellationWhen publishing, only the bare Constellation object is required to perform the publish. Query:{
"command": "publish_constellation",
"apikey": "...",
"constellation": {
"dataType": "Constellation",
"id": "76813079",
"version": "11244085"
},
"message": "Example publish message."
}
Response:{
"constellation": {
"dataType": "Constellation",
"id": "76813079",
"version": "11244089"
},
"result": "success",
"timing": 283.96
}
|
Unlock Constellation
Drops the lock on the given Constellation from "currently editing" down to simply locked to the user.
Command: |
|
Parameters: |
Valid API Key
Constellation object with current ID and Version number |
Return Values: |
Unlocked Constellation object with current id and version numbers
"success" or "failure" depending on whether the query succeeded.
Number of milliseconds spent to produce the result |
Examples: |
Unlock a ConstellationWhen unlocking, only the bare Constellation object is required to perform the unlock. Query:{
"command": "unlock_constellation",
"apikey": "...",
"constellation": {
"dataType": "Constellation",
"id": "76813079",
"version": "11244085"
}
}
Response:{
"constellation": {
"dataType": "Constellation",
"id": "76813079",
"version": "11244089"
},
"result": "success",
"timing": 283.96
}
|
Send Constellation for Review
Sends the given Constellation in SNAC for review. This does not make any updates to the Constellation data in SNAC. If a reviewer is specified, this query will put the Constellation in that user's review queue. If no reviewer is specified, the Constellation will go for general review.
Command: |
|
Parameters: |
Valid API Key
User object of the intended reviewer
Constellation object with at least current ID and Version
A message for the reviewer |
Return Values: |
Full Constellation object with current id and version numbers
"success" or "failure" depending on whether the query succeeded.
Number of milliseconds spent to produce the result |
Examples: |
Sending for ReviewWhen sending for review, only the bare Constellation object is required to perform the request. Query:{
"command": "review_constellation",
"apikey": "...",
"reviewer": {
"...": "..."
},
"constellation": {
"dataType": "Constellation",
"id": "76813079",
"version": "11244085"
},
"message": "Please look over my name headings and biogHist entry"
}
Response:{
"constellation": {
"dataType": "Constellation",
"id": "76813079",
"version": "11244089"
},
"result": "success",
"timing": 283.96
}
|
Delete Constellation
Deletes the given Constellation from SNAC. This does not make any updates to the Constellation data in SNAC before deleting.
Command: |
|
Parameters: |
Valid API Key
Constellation object to delete with at least current ID and Version |
Return Values: |
Full Constellation object deleted
"success" or "failure" depending on whether the query succeeded.
Number of milliseconds spent to produce the result |
Examples: |
Delete a ConstellationWhen deleting, only the bare Constellation object is required to perform the request. Query:{
"command": "delete_constellation",
"apikey": "...",
"constellation": {
"dataType": "Constellation",
"id": "76813079",
"version": "11244085"
}
}
Response:{
"constellation": {
"dataType": "Constellation",
"id": "76813079",
"version": "11244089"
},
"result": "success",
"timing": 283.96
}
|
Reassign Constellation to Another User
Reassigns the given Constellation to a different user, i.e. changes which user to which the Constellation is locked. This does not make any updates to the Constellation data in SNAC.
Command: |
|
Parameters: |
Valid API Key
Constellation object to assign, with at least current ID and Version
User object for the user to whom the Constellation should be assigned |
Return Values: |
Full Constellation object with current id and version numbers
"success" or "failure" depending on whether the query succeeded.
Number of milliseconds spent to produce the result |
Examples: |
Reassign ConstellationWhen reassigning a Constellation, only the bare Constellation object is required to perform the request. Query:{
"command": "reassign_constellation",
"apikey": "...",
"to_user": {
"...": "..."
},
"constellation": {
"dataType": "Constellation",
"id": "76813079",
"version": "11244085"
}
}
Response:{
"constellation": {
"dataType": "Constellation",
"id": "76813079",
"version": "11244089"
},
"result": "success",
"timing": 283.96
}
|
List Recently Published
Returns a list of the most recently published Constellations in SNAC.
Command: |
|
Return Values: |
Simplified Constellation objects {id, ark, nameEntry} of the recently published Constellations
"success" or "failure" depending on whether the query succeeded.
Number of milliseconds spent to produce the result |
Examples: |
Query:{
"command": "recently_published"
}
Response:{
"constellation": [
{
"dataType": "Constellation",
"ark": "http:\/\/snaccooperative.org\/ark:\/99999\/ZICtRNdP",
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Smith, John (1963-2018)"
}
],
"id": 76813079
},
{
"dataType": "Constellation",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6zk9rbc",
"nameEntries": [
{
"dataType": "NameEntry",
"original": "100 Black Men of America, Inc."
}
],
"id": 19735756
},
{
"...": "..."
}
],
"result": "success",
"timing": 1778.94
}
|
List Random Constellations
Returns a random subset of the Constellations in SNAC.
Command: |
|
Return Values: |
Simplified Constellation objects {id, ark, nameEntry} of random Constellations
"success" or "failure" depending on whether the query succeeded.
Number of milliseconds spent to produce the result |
Examples: |
Query:{
"command": "random_constellations"
}
Response:{
"constellation": [
{
"dataType": "Constellation",
"ark": "http:\/\/snaccooperative.org\/ark:\/99999\/ZICtRNdP",
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Smith, John (1963-2018)"
}
],
"id": 76813079
},
{
"dataType": "Constellation",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6zk9rbc",
"nameEntries": [
{
"dataType": "NameEntry",
"original": "100 Black Men of America, Inc."
}
],
"id": 19735756
},
{
"...": "..."
}
],
"result": "success",
"timing": 1778.94
}
|
List Constellations
Returns a list of Constellations based on the query parameters. By default, it will return a subset of published Constellations. If a user object is supplied, additional statuses are allowed to be queried, including "needs review" for all Constellations needing review.
Command: |
|
Parameters: |
Valid API Key
Status of Constellations to return. Currently supported: "published" (default) and "needs review" |
Return Values: |
Simplified objects of {id, version, nameEntry} of the Constellations matching the query |
Examples: |
Query:{
"command": "list_constellations"
}
Response:{
"results": [
{
"id": "76806764",
"version": "11243376",
"nameEntry": "100 Black Men of Charleston, Inc."
},
{
"id": "32319",
"version": "11243333",
"nameEntry": "Atlantic Yacht Club"
},
{
"id": "1960345",
"version": "11243501",
"nameEntry": "Boardman, Mabel Thorp, 1860-1946"
},
{
"...": "..."
}
],
"timing": 62303.38
}
|
Get Constellation History
Returns the edit history of the given Constellation.
Command: |
|
Parameters: |
Constellation ID |
Return Values: |
Full current Constellation Object
List of history objects, in reverse order, describing what has happened to the Constellation through the current version.
Number of milliseconds spent to produce the result |
Examples: |
Query:{
"command": "constellation_history",
"constellationid": 76813079
}
Response:{
"constellation": {
"dataType": "Constellation",
"entityType": {
"id": 700,
"term": "person"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Smith, John (Doctor), 1963-2018",
"preferenceScore": 99,
"id": "76813080",
"version": "11244089"
}
],
"id": "76813079",
"version": "11244089"
},
"history": [
{
"date": "2017-04-19T10:34:47",
"userName": "user@gmail.com",
"fullName": "Example User",
"version": "11244089",
"status": "published",
"note": ""
},
{
"date": "2016-08-19T20:59:47",
"userName": "system@localhost",
"fullName": "System Service",
"version": "11223504",
"status": "published",
"note": ""
},
{
"date": "2016-08-19T20:59:47",
"userName": "system@localhost",
"fullName": "System Service",
"version": "11223502",
"status": "ingest cpf",
"note": "",
"data": {
"maintenanceStatus": {
"id": "7656",
"term": "revised"
},
"maintenanceAgency": "SNAC: Social Networks and Archival Context Project",
"maintenanceEvents": [
{
"dataType": "MaintenanceEvent",
"eventType": {
"id": "704",
"term": "revised"
},
"eventDateTime": "2015-09-18",
"agentType": {
"id": "687",
"term": "machine"
},
"agent": "CPF merge program",
"eventDescription": "Merge v2.0"
}
],
"sameAsRelations": [
{
"dataType": "SameAs",
"type": {
"id": 28224,
"term": "MergedRecord",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#MergedRecord"
},
"uri": "OCLC-TXG-6843155.r02",
"id": "76757792",
"version": "11223503"
}
]
}
}
],
"timing": 278.9
}
|
Download Constellation
Returns the full Constellation in the requested format. To perform a direct download, without JSON wrapping, submit a request to the webUI interface, https://snaccooperative.org/download/{constellationid}?type={type} or https://snaccooperative.org/download?arkid={ark}&type={type}.
Command: |
|
Parameters: |
Constellation ID for Constellation to read
Version of the Constellation to read
What type of file to return: constellation_json or eac_cpf.
ARK ID for Constellation to read, of the form 'http://n2t.net/ark:/99166/xxxxxxxx' |
Return Values: |
File information object, including mime-type, filename, and base64-encoded content of the file. |
Examples: |
Query:{
"command": "download_constellation",
"constellationid": 76813079,
"type": "eac-cpf"
}
Response:{
"file": {
"mime-type": "text\/xml",
"filename": "99999-ZICtRNdP.xml",
"content": "... BASE64 ..."
},
"timing": 399.35
}
|
List Maybe-Same Constellations
Returns a list of Constellations denoted as maybe-same-as the given Constellation. If the user object is given, it will contain mergeable flags to denote if the user has permission to merge any of the Constellations.
Command: |
|
Parameters: |
Valid API Key
Constellation ID |
Return Values: |
Boolean value denoting whether the Constellations can be merged by this user
Summary Constellation Object of the requested Constellation
Array of objects, each containing a "mergeable" flag and a Constellation Object of the Constellation asserted to be the maybe the same.
Number of milliseconds spent to produce the result |
Examples: |
Query:{
"command": "constellation_list_maybesame",
"apikey": "...",
"constellationid": 66598997
}
Response:{
"mergeable": true,
"constellation": {
"dataType": "Constellation",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6rf67f4",
"entityType": {
"id": "700",
"term": "person",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Person",
"type": "entity_type"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Slemp, C. Bascom (Campbell Bascom), 1870-1943",
"preferenceScore": "99",
"id": "66599026",
"version": "9740651"
}
],
"biogHists": [
{
"dataType": "BiogHist",
"text": "...",
"id": "66598998",
"version": "9740651"
}
],
"id": 66598997,
"version": "9740652"
},
"maybe_same": [
{
"constellation": {
"dataType": "Constellation",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6k219nd",
"entityType": {
"id": "700",
"term": "person",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Person",
"type": "entity_type"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Slemp, C. B.",
"preferenceScore": "1",
"id": "15919565",
"version": "2323442"
}
],
"id": "15919563",
"version": "2323443"
},
"mergeable": true
},
{
"constellation": {
"dataType": "Constellation",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6wj8g41",
"entityType": {
"id": "700",
"term": "person",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Person",
"type": "entity_type"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Slemp, Bascom",
"preferenceScore": "1",
"id": "68374832",
"version": "9995489"
}
],
"id": "68374830",
"version": "9995490"
},
"mergeable": true
}
],
"timing": 539.29
}
|
Add Maybe-Same Constellation Assertions
Makes a maybe-same assertion between the constellations specified.
Command: |
|
Parameters: |
Valid API Key
User's assertion statement about the similarity of these Constellations
2 or more Constellation IDs to assert as maybe_same |
Return Values: |
"success" or "failure" depending on whether the merge succeeded.
Number of milliseconds spent to produce the result |
Examples: |
Query:{
"command": "constellation_add_maybesame",
"apikey": "...",
"constellationids": [
123456,
987654,
626505
],
"assertion": "These three all have the same name and come from the same holding institution"
}
Response:{
"result": "success",
"timing": 246.13
}
|
Compute Constellation Diff
Computes the difference between the two given Constellations. Returns Constellation objects containing: only those items in the first, only those items in the second, and components shared.
Command: |
|
Parameters: |
Constellation ID for one Constellation to compare
Constellation Version to compare. If not set, it will compare the published version.
Constellation ID for the other Constellation to compare
Constellation Version to compare. If not set, it will compare the published version. |
Return Values: |
Constellation object containing only data distinct to the first Constellation
Constellation object containing only data distinct to the second Constellation
Constellation object containing only data shared by both Constellations
Boolean value denoting whether these two Constellations can be merged by this user |
Examples: |
DiffQuery:{
"command": "constellation_diff",
"apikey": "...",
"constellationid1": 123456,
"constellationid2": 987654
}
Response:{
"result": "success",
"constellation1": {
"...": "..."
},
"constellation2": {
"...": "..."
},
"intersection": {
"...": "..."
},
"mergeable": true
}
|
Compute Constellation Diff and Set Merge
Computes the difference between the two given Constellations. Checks out the two Constellations in editing for the given user to allow a merge. Returns Constellation objects containing: only those items in the first, only those items in the second, and components shared.
Command: |
|
Parameters: |
Valid API Key
Constellation ID for one Constellation to compare
Constellation ID for the other Constellation to compare |
Return Values: |
Constellation object containing only data distinct to the first Constellation
Constellation object containing only data distinct to the second Constellation
Constellation object containing only data shared by both Constellations
Boolean value denoting whether these two Constellations can be merged by this user |
Examples: |
Successful Mergeable DiffIf the given user has permission to check both Constellations out for editing, then the system will automatically check them out to the user, produce the diff, and denote to the user in the mergeable flag that the user may merge these constellations. Query:{
"command": "constellation_diff_merge",
"apikey": "...",
"constellationid1": 123456,
"constellationid2": 987654
}
Response:{
"result": "success",
"constellation1": {
"...": "..."
},
"constellation2": {
"...": "..."
},
"intersection": {
"...": "..."
},
"mergeable": true
}
|
Merge Constellations
Given Constellation IDs and a full, merged, Constellation, creates a new Constellation in SNAC from the given Constellation and sets all Constellations given by the IDs to be "tombstoned" and redirected to the new, merged, Constellation.
Command: |
|
Parameters: |
Valid API Key
2 or more Constellation IDs to merge together. Each Constellation will be "tombstoned" and point to a new Constellation that matches the one provided by the user in the Constellation parameter.
Full merged Constellation object. The version of the Constellation here will be considered by SNAC as the merged version; it will be written as a new Constellation. |
Return Values: |
Full Constellation object with current id and version numbers
"success" or "failure" depending on whether the merge succeeded.
Number of milliseconds spent to produce the result |
Examples: |
Merge three ConstellationsIf we want to merge three Constellations into one, which only has a name entry, we would provide all IDs and the appropriate merged version. Query:{
"command": "constellation_merge",
"apikey": "...",
"constellationids": [
123456,
987654,
626505
],
"constellation": {
"dataType": "Constellation",
"entityType": {
"id": 700,
"term": "person"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Smith, John (Doctor), 1963-2018",
"preferenceScore": 99
}
]
}
}
Response:{
"constellation": {
"dataType": "Constellation",
"status": "published",
"entityType": {
"id": 700,
"term": "person"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Smith, John (Doctor), 1963-2018",
"preferenceScore": 99,
"id": "76813080",
"version": "11244089"
}
],
"id": "76813079",
"version": "11244089"
},
"result": "success",
"timing": 583.96
}
|
Automatically Merge Constellations
Given Constellation IDs, creates a new Constellation in SNAC from the combined data from all Constellations, "tombstones" the originals, and redirects thier IDs to the new, merged, Constellation.
Command: |
|
Parameters: |
Valid API Key
2 or more Constellation IDs to merge together. Each Constellation will be "tombstoned" and point to a new Constellation that matches the one provided by the user in the Constellation parameter. |
Return Values: |
Full Constellation object with current id and version numbers
"success" or "failure" depending on whether the merge succeeded.
Number of milliseconds spent to produce the result |
Examples: |
Auto-merge three ConstellationsIf we want to merge three Constellations into one, which only has a name entry, we would provide all IDs and the system automatically creates a merged version. Query:{
"command": "constellation_auto_merge",
"apikey": "...",
"constellationids": [
123456,
987654,
626505
]
}
Response:{
"constellation": {
"dataType": "Constellation",
"status": "published",
"entityType": {
"id": 700,
"term": "person"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Smith, John (Doctor), 1963-2018",
"preferenceScore": 99,
"id": "76813080",
"version": "11244089"
}
],
"id": "76813079",
"version": "11244089"
},
"result": "success",
"timing": 738.96
}
|
Read Constellation
Returns the full Constellation for viewing. Either a constellationid or arkid are required. If a constellationid and version are both supplied, this will read that version of the constellation, if it exists.
Command: |
|
Parameters: |
Constellation ID for Constellation to read
Version of the Constellation to read
How much of the Constellation to return. Without this parameter, the entire Constellation is returned. If set to "summary", a summary is returned without relationships.
ARK ID for Constellation to read, of the form 'http://n2t.net/ark:/99166/xxxxxxxx'
One of the Constellation's external links, for example 'http://en.wikipedia.org/wiki/Harriet_Tubman' |
Return Values: |
"success" if one Constellation is returned, "success-notice" if there is a special return.
Message relating to the "success-notice" result. Contains a "text" string including a human-readable note and an "info" object of additional information about the Constellation.
Full Constellation object with current id and version numbers. If the ID/Ark given point to a Constellation that has been split, multiple Constellation objects will be returned instead.
Number of other Constellations in SNAC listed as maybe-the-same as this one.
Number of milliseconds spent to produce the result |
Examples: |
Read a ConstellationBy requesting simply a constellationid, we get the current published version of the Constellation. Query:{
"command": "read",
"constellationid": 76813079
}
Response:{
"result": "success",
"maybesame_count": 0,
"constellation": {
"dataType": "Constellation",
"status": "editable",
"ark": "http:\/\/snaccooperative.org\/ark:\/99999\/ZICtRNdP",
"entityType": {
"id": "700",
"term": "person",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Person",
"type": "entity_type"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Smith, John (1963-2018)",
"preferenceScore": "99",
"components": [
{
"dataType": "NameComponent",
"text": "Smith, John (1963-2018)",
"order": "0",
"type": {
"id": "400228",
"term": "Name",
"type": "name_component"
},
"id": "76813081",
"version": "11244084"
}
],
"id": "76813080",
"version": "11244084"
}
],
"id": "76813079",
"version": "11244087"
},
"timing": 230.63
}
|
Edit Constellation
Check out the Constellation for editing.
Command: |
|
Parameters: |
Valid API Key
Constellation ID for Constellation to edit |
Return Values: |
Reviewer's note, if set by another user.
Full Constellation object with current id and version numbers, ready for editing. Those id/version values must be present with future update queries.
Number of milliseconds spent to produce the result |
Examples: |
Edit a ConstellationQuery:{
"command": "edit",
"apikey": "...",
"constellationid": 76813079
}
Response:{
"constellation": {
"dataType": "Constellation",
"status": "editable",
"ark": "http:\/\/snaccooperative.org\/ark:\/99999\/ZICtRNdP",
"entityType": {
"id": "700",
"term": "person",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Person",
"type": "entity_type"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Smith, John (1963-2018)",
"preferenceScore": "99",
"components": [
{
"dataType": "NameComponent",
"text": "Smith, John (1963-2018)",
"order": "0",
"type": {
"id": "400228",
"term": "Name",
"type": "name_component"
},
"id": "76813081",
"version": "11244084"
}
],
"id": "76813080",
"version": "11244084"
}
],
"id": "76813079",
"version": "11244087"
},
"timing": 230.63
}
|
Search Constellations
Search for a Constellation, returning a list of possible matches.
Command: |
|
Parameters: |
Search term to query against SNAC
Position in the results to start. Begin with 0
Number of results to return
The entity type of the identity to search (person, corporateBody, family)
Whether or not to search biographical histories for the search term
Facets to use in searching.
What type of search to perform. By default, performs standard keyword search. Passing 'autocomplete' will use left-anchored autocomplete search. Passing 'advanced' will allow wildcards and other advanced features. |
Return Values: |
Simplified Constellation objects {id, ark, nameEntry} of random Constellations
List of facets that are included in the current search results
Search term to query against SNAC
Number of results returned in this request
Number of total search results
Page number of results based on total and count
Number of total pages of results based on total and count
What type of search to perform. By default, performs standard keyword search. Passing 'autocomplete' will use left-anchored autocomplete search. Passing 'advanced' will allow wildcards and other advanced features.
Number of milliseconds spent to produce the result |
Examples: |
Basic SearchA basic search for "Washington" among people. Query:{
"command": "search",
"term": "Washington",
"entity_type": "person",
"start": 0,
"count": 3
}
Response:{
"total": 2170,
"results": [
{
"dataType": "Constellation",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6028ps4",
"entityType": {
"id": "700",
"term": "person",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Person",
"type": "entity_type"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Washington, George, 1732-1799",
"preferenceScore": "99",
"id": "57007281",
"version": "8341616"
}
],
"biogHists": [
{
"dataType": "BiogHist",
"text": "...",
"id": "57005056",
"version": "8341616"
}
],
"id": "57005055",
"version": "11243948"
},
{
"dataType": "Constellation",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6fb5542",
"entityType": {
"id": "700",
"term": "person",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Person",
"type": "entity_type"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Irving, Washington, 1783-1859",
"preferenceScore": "99",
"id": "58214892",
"version": "8509754"
}
],
"biogHists": [
{
"dataType": "BiogHist",
"text": "...",
"id": "58214480",
"version": "8509754"
}
],
"id": "58214479",
"version": "8509755"
},
{
"dataType": "Constellation",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6zp5fs0",
"entityType": {
"id": "700",
"term": "person",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Person",
"type": "entity_type"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Washington, Joe",
"preferenceScore": "4",
"id": "64784398",
"version": "9470486"
}
],
"id": "64784275",
"version": "9470487"
}
],
"aggregations": {
"occupation": [
{
"term": "Army officers.",
"count": 8
},
{
"term": "Authors.",
"count": 7
},
{
"term": "Lawyers.",
"count": 7
},
{
"term": "Collectors.",
"count": 6
},
{
"term": "Diplomats.",
"count": 6
},
{
"term": "Educators.",
"count": 5
},
{
"term": "Clergy.",
"count": 4
},
{
"term": "Farmers.",
"count": 4
},
{
"term": "Jurists.",
"count": 4
},
{
"term": "Soldiers--United States.",
"count": 4
}
],
"subject": [
{
"term": "Agriculture",
"count": 14
},
{
"term": "Indians of North America",
"count": 11
},
{
"term": "Slavery",
"count": 11
},
{
"term": "African Americans",
"count": 9
},
{
"term": "Frontier and pioneer life",
"count": 9
},
{
"term": "Lawyers",
"count": 9
},
{
"term": "Physicians",
"count": 9
},
{
"term": "Real property",
"count": 9
},
{
"term": "Families--Social life and customs",
"count": 8
},
{
"term": "Pioneers",
"count": 8
}
],
"activity": []
},
"pagination": 15,
"page": 0,
"count": 3,
"term": "Washington",
"search_type": "default",
"timing": 1092.14
}
|
Browse Constellations
Given a query name heading, returns the surrounding matching Constellations (in alphabetical order).
Command: |
|
Parameters: |
Search term to query against SNAC
The entity type of the identity to search (person, corporateBody, family)
Whether the "requested" term in the browse list should be in the "middle" of the list, "before", or "after".
Constellation ID if needed to distinguish between identical names in the response list |
Return Values: |
An array of names from SNAC, in a special format. Includes the preferred name entry of a Constellation with its ark, Constellation ID, degree, resources, entity type, and timestamp of when it was updated. These results also include the normalized lower-case name entry.
"success" or "failure" depending on whether the query succeeded.
Number of milliseconds spent to produce the result |
Examples: |
Query:{
"command": "browse",
"term": "Washington",
"position": "middle"
}
Response:{
"results": [
{
"name_entry": "Wash, Frank H. (Frank Hord), 1867-",
"name_entry_lower": "wash, frank h. (frank hord), 1867-",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6xh8hz5",
"ic_id": "27734815",
"degree": "0",
"resources": "3",
"entity_type": "person",
"timestamp": "2017-04-14 16:04:00.34925"
},
{
"name_entry": "Wash. Gallery of Mod. Art",
"name_entry_lower": "wash. gallery of mod. art",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6fk5r89",
"ic_id": "57074890",
"degree": "1",
"resources": "1",
"entity_type": "corporateBody",
"timestamp": "2017-04-14 22:37:24.150557"
},
{
"name_entry": "Washiashi, Fumio",
"name_entry_lower": "washiashi, fumio",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6946grx",
"ic_id": "39098837",
"degree": "1",
"resources": "1",
"entity_type": "person",
"timestamp": "2017-04-14 18:30:16.606595"
},
{
"name_entry": "Washida, Kyo.",
"name_entry_lower": "washida, kyo.",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w64n0f57",
"ic_id": "39156515",
"degree": "0",
"resources": "1",
"entity_type": "person",
"timestamp": "2017-04-14 18:30:55.68445"
},
{
"name_entry": "W. A. Shields",
"name_entry_lower": "w. a. shields",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6kj60fq",
"ic_id": "27654177",
"degree": "1",
"resources": "1",
"entity_type": "person",
"timestamp": "2017-04-14 16:03:04.819829"
},
{
"name_entry": "Washinawatok, Gwendolyn Dodge.",
"name_entry_lower": "washinawatok, gwendolyn dodge.",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6qr6f0k",
"ic_id": "75832012",
"degree": "0",
"resources": "1",
"entity_type": "person",
"timestamp": "2017-04-15 03:10:03.948293"
},
{
"name_entry": "Washines, Lorena.",
"name_entry_lower": "washines, lorena.",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6vq3w4h",
"ic_id": "6563783",
"degree": "1",
"resources": "1",
"entity_type": "person",
"timestamp": "2017-04-14 11:55:33.983345"
},
{
"name_entry": "Washines, Lorena Neaman, 1949-",
"name_entry_lower": "washines, lorena neaman, 1949-",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6rr43x3",
"ic_id": "727678",
"degree": "2",
"resources": "1",
"entity_type": "person",
"timestamp": "2017-04-14 10:51:38.349649"
},
{
"name_entry": "Washinggon, G.",
"name_entry_lower": "washinggon, g.",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w63d067h",
"ic_id": "73588329",
"degree": "1",
"resources": "1",
"entity_type": "person",
"timestamp": "2017-04-15 02:36:18.961325"
},
{
"name_entry": "Washingon Public Power Supply System Organization",
"name_entry_lower": "washingon public power supply system organization",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6mf4fhh",
"ic_id": "32287913",
"degree": "1",
"resources": "1",
"entity_type": "corporateBody",
"timestamp": "2017-04-14 17:02:08.145018"
},
{
"name_entry": "Washington",
"name_entry_lower": "washington",
"ark": "http:\/\/snaccooperative.org\/ark:\/99999\/Z3Fcdj2v",
"ic_id": "76806647",
"degree": "6",
"resources": "16",
"entity_type": "person",
"timestamp": "2017-05-16 10:21:36.134303"
},
{
"name_entry": "Washington",
"name_entry_lower": "washington",
"ark": "http:\/\/snaccooperative.org\/ark:\/99999\/ZSpIRzTp",
"ic_id": "76806699",
"degree": "6",
"resources": "16",
"entity_type": "person",
"timestamp": "2017-05-16 10:22:13.54157"
},
{
"name_entry": "Washington ",
"name_entry_lower": "washington ",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6w52tbs",
"ic_id": "22801605",
"degree": "1",
"resources": "1",
"entity_type": "family",
"timestamp": "2017-04-14 15:01:53.291301"
},
{
"name_entry": "Washington, 1777",
"name_entry_lower": "washington, 1777",
"ark": "http:\/\/snaccooperative.org\/ark:\/99999\/ZCngp9Os",
"ic_id": "76806751",
"degree": "2",
"resources": "1",
"entity_type": "person",
"timestamp": "2017-05-16 10:23:14.746397"
},
{
"name_entry": "Washington, Aaron",
"name_entry_lower": "washington, aaron",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6hr6r64",
"ic_id": "9579544",
"degree": "1",
"resources": "1",
"entity_type": "person",
"timestamp": "2017-04-14 12:29:17.04413"
},
{
"name_entry": "Washington Abstinance Society.",
"name_entry_lower": "washington abstinance society.",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6rz7btv",
"ic_id": "16198707",
"degree": "1",
"resources": "1",
"entity_type": "corporateBody",
"timestamp": "2017-04-14 13:43:39.761765"
},
{
"name_entry": "Washington Academy.",
"name_entry_lower": "washington academy.",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6b61j8k",
"ic_id": "20509409",
"degree": "0",
"resources": "1",
"entity_type": "corporateBody",
"timestamp": "2017-04-14 14:34:04.568368"
},
{
"name_entry": "Washington Academy.",
"name_entry_lower": "washington academy.",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w60c969j",
"ic_id": "35410477",
"degree": "1",
"resources": "1",
"entity_type": "corporateBody",
"timestamp": "2017-04-14 17:40:40.749371"
},
{
"name_entry": "Washington Academy (Lexington, Va.)",
"name_entry_lower": "washington academy (lexington, va.)",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6713673",
"ic_id": "53257876",
"degree": "5",
"resources": "7",
"entity_type": "corporateBody",
"timestamp": "2017-04-14 21:42:27.886325"
},
{
"name_entry": "Washington Academy of Sciences",
"name_entry_lower": "washington academy of sciences",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w64w024n",
"ic_id": "16299930",
"degree": "1",
"resources": "1",
"entity_type": "person",
"timestamp": "2017-04-14 13:44:45.632322"
}
],
"result": "success",
"timing": 440.19
}
|
Insert Resource
Given a Resource, inserts it into SNAC's resource cache.
Command: |
|
Parameters: |
Resource object to write to SNAC, with "operation" set to "insert".
Valid API Key |
Return Values: |
Full resource object as written to SNAC
"success" or "failure" depending on whether the query succeeded.
Number of milliseconds spent to produce the result |
Examples: |
Query:{
"command": "insert_resource",
"resource": {
"dataType": "Resource",
"title": "My Title",
"link": "https:\/\/mylink.com",
"abstract": "This is a full abstract",
"source": "My full citation",
"documentType": {
"id": "696",
"term": "ArchivalResource",
"type": "document_type"
},
"extent": "20 pages",
"repository": {
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6kq8qkp",
"dataType": "Constellation",
"id": "76763300"
},
"operation": "insert"
},
"apikey": "..."
}
Response:{
"resource": {
"dataType": "Resource",
"documentType": {
"id": "696",
"term": "ArchivalResource",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#ArchivalResource",
"type": "document_type"
},
"link": "https:\/\/mylink.com",
"source": "My full citation",
"title": "My Title",
"abstract": "This is a full abstract",
"extent": "20 pages",
"repository": {
"dataType": "Constellation",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6kq8qkp",
"entityType": {
"id": "698",
"term": "corporateBody",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#CorporateBody",
"type": "entity_type"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Campbell University, Wiggins Memorial Library",
"preferenceScore": "99",
"id": "76763301",
"version": "11225237"
}
],
"places": [
{
"dataType": "Place",
"original": "Campbell University, Wiggins Memorial Library",
"type": {
"id": "400242",
"term": "Address",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Address",
"type": "place_type"
},
"address": [
{
"dataType": "AddressLine",
"text": "Wiggins Memorial Library",
"order": "0",
"type": {
"id": "400243",
"term": "Unspecified",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Unspecified",
"type": "address_part"
},
"id": "76763306",
"version": "11225237"
},
{
"dataType": "AddressLine",
"text": "P.O. Box 98 or 113 Main Street",
"order": "1",
"type": {
"id": "400243",
"term": "Unspecified",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Unspecified",
"type": "address_part"
},
"id": "76763307",
"version": "11225237"
},
{
"dataType": "AddressLine",
"text": "Buies Creek",
"order": "2",
"type": {
"id": "400243",
"term": "Unspecified",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Unspecified",
"type": "address_part"
},
"id": "76763308",
"version": "11225237"
},
{
"dataType": "AddressLine",
"text": "US-NC",
"order": "3",
"type": {
"id": "400243",
"term": "Unspecified",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Unspecified",
"type": "address_part"
},
"id": "76763309",
"version": "11225237"
},
{
"dataType": "AddressLine",
"text": "27506",
"order": "4",
"type": {
"id": "400243",
"term": "Unspecified",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Unspecified",
"type": "address_part"
},
"id": "76763310",
"version": "11225237"
},
{
"dataType": "AddressLine",
"text": "US",
"order": "5",
"type": {
"id": "400243",
"term": "Unspecified",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Unspecified",
"type": "address_part"
},
"id": "76763311",
"version": "11225237"
}
],
"geoplace": {
"id": "16695",
"name": "Campbell University, Wiggins Memorial Library",
"latitude": "35.4070892",
"longitude": "-78.7394028"
},
"confirmed": true,
"id": "76763305",
"version": "11225237"
}
],
"id": "76763300",
"version": "11225240"
},
"id": "11612307",
"version": "8359251"
},
"result": "success",
"timing": 706.34
}
|
Read Resource
Read the entire Resource from SNAC's resource cache.
Command: |
|
Parameters: |
The resource ID from SNAC to read |
Return Values: |
Full resource object from SNAC
Number of milliseconds spent to produce the result |
Examples: |
Query:{
"command": "read_resource",
"resourceid": 7149468
}
Response:{
"resource": {
"dataType": "Resource",
"documentType": {
"id": "696",
"term": "ArchivalResource",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#ArchivalResource",
"type": "document_type"
},
"link": "https:\/\/www.worldcat.org\/oclc\/25756829",
"source": "...",
"title": "Papers, 1881-1958.",
"abstract": "This collection contains business papers, political papers, and family papers. ",
"extent": "4 boxes (2 cu.ft.)",
"originationNames": [
{
"dataType": "OriginationName",
"name": "Avary, Robert Lee.",
"id": "9120396",
"version": "7149468"
}
],
"repository": {
"dataType": "Constellation",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6nq2ssj",
"entityType": {
"id": "698",
"term": "corporateBody",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#CorporateBody",
"type": "entity_type"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Atlanta History Center, Kenan Research Center \/ Cherokee Garden Library",
"preferenceScore": "99",
"id": "76760880",
"version": "11224337"
}
],
"places": [
{
"dataType": "Place",
"original": "Atlanta History Center, Kenan Research Center \/ Cherokee Garden Library",
"type": {
"id": "400242",
"term": "Address",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Address",
"type": "place_type"
},
"address": [
{
"dataType": "AddressLine",
"text": "130 W. Paces Ferry Rd. NW",
"order": "0",
"type": {
"id": "400243",
"term": "Unspecified",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Unspecified",
"type": "address_part"
},
"id": "76760885",
"version": "11224337"
},
{
"dataType": "AddressLine",
"text": "Atlanta",
"order": "1",
"type": {
"id": "400243",
"term": "Unspecified",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Unspecified",
"type": "address_part"
},
"id": "76760886",
"version": "11224337"
},
{
"dataType": "AddressLine",
"text": "US-GA",
"order": "2",
"type": {
"id": "400243",
"term": "Unspecified",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Unspecified",
"type": "address_part"
},
"id": "76760887",
"version": "11224337"
},
{
"dataType": "AddressLine",
"text": "30305-1366",
"order": "3",
"type": {
"id": "400243",
"term": "Unspecified",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Unspecified",
"type": "address_part"
},
"id": "76760888",
"version": "11224337"
},
{
"dataType": "AddressLine",
"text": "US",
"order": "4",
"type": {
"id": "400243",
"term": "Unspecified",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Unspecified",
"type": "address_part"
},
"id": "76760889",
"version": "11224337"
}
],
"geoplace": {
"id": "16354",
"name": "Atlanta History Center, Kenan Research Center \/ Cherokee Garden Library",
"latitude": "33.8411636",
"longitude": "-84.3860474"
},
"confirmed": true,
"id": "76760884",
"version": "11224337"
}
],
"id": "76760879",
"version": "11224340"
},
"id": "7149468",
"version": "7149468"
},
"timing": 18.4
}
|
Search Resources
Searches the resource cache in SNAC. Returns the top matches.
Command: |
|
Parameters: |
Search term to query against the SNAC resource cache.
Number of results to return |
Return Values: |
List of matching Resource objects from SNAC
Number of total search results
Page number of results based on total and count
Number of total pages of results based on total and count
Number of milliseconds spent to produce the result |
Examples: |
Query:{
"command": "resource_search",
"term": "Papers"
}
Response:{
"total": 308000,
"results": [
{
"dataType": "Resource",
"documentType": {
"id": "696",
"term": "ArchivalResource",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#ArchivalResource",
"type": "document_type"
},
"link": "https:\/\/www.worldcat.org\/oclc\/25756829",
"source": "...",
"title": "Papers, 1881-1958.",
"abstract": "This collection contains business papers, political papers, and family papers. ",
"extent": "4 boxes (2 cu.ft.)",
"originationNames": [
{
"dataType": "OriginationName",
"name": "Avary, Robert Lee.",
"id": "9120396",
"version": "7149468"
}
],
"repository": {
"dataType": "Constellation",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6nq2ssj",
"entityType": {
"id": "698",
"term": "corporateBody",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#CorporateBody",
"type": "entity_type"
},
"nameEntries": [
{
"dataType": "NameEntry",
"original": "Atlanta History Center, Kenan Research Center \/ Cherokee Garden Library",
"preferenceScore": "99",
"id": "76760880",
"version": "11224337"
}
],
"places": [
{
"dataType": "Place",
"original": "Atlanta History Center, Kenan Research Center \/ Cherokee Garden Library",
"type": {
"id": "400242",
"term": "Address",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Address",
"type": "place_type"
},
"address": [
{
"dataType": "AddressLine",
"text": "130 W. Paces Ferry Rd. NW",
"order": "0",
"type": {
"id": "400243",
"term": "Unspecified",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Unspecified",
"type": "address_part"
},
"id": "76760885",
"version": "11224337"
},
{
"dataType": "AddressLine",
"text": "Atlanta",
"order": "1",
"type": {
"id": "400243",
"term": "Unspecified",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Unspecified",
"type": "address_part"
},
"id": "76760886",
"version": "11224337"
},
{
"dataType": "AddressLine",
"text": "US-GA",
"order": "2",
"type": {
"id": "400243",
"term": "Unspecified",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Unspecified",
"type": "address_part"
},
"id": "76760887",
"version": "11224337"
},
{
"dataType": "AddressLine",
"text": "30305-1366",
"order": "3",
"type": {
"id": "400243",
"term": "Unspecified",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Unspecified",
"type": "address_part"
},
"id": "76760888",
"version": "11224337"
},
{
"dataType": "AddressLine",
"text": "US",
"order": "4",
"type": {
"id": "400243",
"term": "Unspecified",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#Unspecified",
"type": "address_part"
},
"id": "76760889",
"version": "11224337"
}
],
"geoplace": {
"id": "16354",
"name": "Atlanta History Center, Kenan Research Center \/ Cherokee Garden Library",
"latitude": "33.8411636",
"longitude": "-84.3860474"
},
"confirmed": true,
"id": "76760884",
"version": "11224337"
}
],
"id": "76760879",
"version": "11224340"
},
"id": "7149468",
"version": "7149468"
},
{
"dataType": "Resource",
"documentType": {
"id": "697",
"term": "BibliographicResource",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#BibliographicResource",
"type": "document_type"
},
"title": "Johnston family papers, 1824-1922",
"id": "2522525",
"version": "2522525"
},
{
"dataType": "Resource",
"documentType": {
"id": "697",
"term": "BibliographicResource",
"uri": "http:\/\/socialarchive.iath.virginia.edu\/control\/term#BibliographicResource",
"type": "document_type"
},
"title": "Mathematical papers : selected papers",
"id": "3267730",
"version": "3267730"
}
],
"pagination": 30800,
"page": 0,
"timing": 5846.73
}
|
Delete Resource
Deletes a given resource and all its relationships
Command: |
|
Parameters: |
ID of the resource to delete |
Return Values: |
"success" or "failure" depending on whether the query succeeded.
Number of milliseconds spent to produce the result |
Examples: |
Query:{
"command": "delete_resource",
"resourceid": "76763300",
"apikey": "..."
}
Response:{
"result": "success"
}
|
Elastic Search Query
Search through the Constellation indexes using Elastic Search syntax.
Command: |
|
Parameters: |
JSON-formatted Elastic Search query. This would be the "query" portion of an Elastic Search API call. We will automatically include the index and type for Elastic Search.
Number of results to return
Starting point in the results, 0-based |
Return Values: |
Full results directly from Elastic Search
Number of milliseconds spent to produce the result |
Examples: |
Basic Elastic Search QueryA basic search for "poets". Query:{
"command": "elastic",
"query": {
"simple_query_string": {
"query": "poets",
"default_operator": "and"
}
},
"size": 2,
"from": 0
}
Response:{
"results": {
"took": 3,
"timed_out": false,
"hits": {
"total": 4714,
"max_score": 2.8193178,
"hits": [
{
"_id": "36683640",
"_score": 2.8193178,
"_source": {
"nameEntry": "Grano, Paul, 1894-1975",
"entityType": "person",
"arkID": "http:\/\/n2t.net\/ark:\/99166\/w6cv522g",
"id": 36683640,
"degree": 5,
"resources": 15,
"subject": [
"Poets, Australian--20th century",
"Australian poetry"
],
"occupation": [
"Poets",
"Poets."
],
"activity": [],
"biogHist": [],
"hasImage": false,
"imageURL": null,
"imageMeta": null,
"timestamp": "2017-11-01T19:15:51-04:00"
}
},
{
"_id": "50543201",
"_score": 2.794444,
"_source": {
"nameEntry": "O'Hara, John Bernard, 1862-1927",
"entityType": "person",
"arkID": "http:\/\/n2t.net\/ark:\/99166\/w6wq071g",
"id": 50543201,
"degree": 7,
"resources": 5,
"subject": [
"Poets, Australian--20th century"
],
"occupation": [
"Poets",
"Poets."
],
"activity": [],
"biogHist": [],
"hasImage": false,
"imageURL": null,
"imageMeta": null,
"timestamp": "2017-11-01T20:03:33-04:00"
}
}
]
}
},
"result": "success",
"timing": 18.34
}
|
Parse EAC-CPF XML to Constellation (Pre-Alpha)
Parses a given EAC-CPF file into a Constellation JSON object using the SNAC profile.
Command: |
|
Add external links to a constellation
Links a constellation to an external identity on sites such as Wikipedia, VIAF, etc.
Command: |
|
Parameters: |
Valid API Key
Constellation ID
An array of URIs to link this constellation to. |
Examples: |
Add sameAs linksChecks out a given constellation, adds external links and publishes the constellation Query:{
"command": "add_sameas",
"constellationid": 73093297,
"sameas_uris": [
"https:\/\/en.wikipedia.org\/wiki\/Franciscus_Gomarus",
"https:\/\/id.loc.gov\/authorities\/names\/nb98048106"
],
"apikey": "..."
}
Response:{
"constellation": {
"dataType": "Constellation",
"status": "currently editing",
"ark": "http:\/\/n2t.net\/ark:\/99166\/w6vz535m",
"sameAsRelations": [
{
"dataType": "SameAs",
"type": {
"id": 28225
},
"uri": "https:\/\/id.loc.gov\/authorities\/names\/nb98048106",
"id": "83129381",
"version": "11258569",
"operation": "insert"
},
{
"dataType": "SameAs",
"type": {
"id": 28225
},
"uri": "https:\/\/id.loc.gov\/authorities\/names\/nb98048106",
"id": "83129382",
"version": "11258569",
"operation": "insert"
}
],
"id": 73093297,
"version": "11258570"
},
"result": "success",
"timing": 3052.06
}
|
Get Holdings
Get an array of resources held by a Holding Repository
Command: |
|
Parameters: |
Constellation ID |
Examples: |
Get HoldingsGet an array of resources held by a Holding Repository Query:{
"command": "get_holdings",
"constellationid": "76778184"
}
Response:{
"resources": [
{
"id": "7677119",
"title": "Report of a focused visit to Oakland Community College ...",
"href": "http:\/\/www.worldcat.org\/oclc\/54358612",
"relation_count": 2
}
],
"result": "success",
"timing": 792.5
}
|
Shared Resources
Get an array of resources related to both constellations
Command: |
|
Parameters: |
Constellation ID
Constellation ID |
Examples: |
Shared ResourcesGet an array of resources held by a Holding Repository Query:{
"command": "shared_resources",
"icid1": "29260863",
"icid2": "50307952"
}
Response:{
"resources": [
{
"id": "7960925",
"title": "C.S. Lewis collection. [1939].",
"href": "http:\/\/www.worldcat.org\/oclc\/667850821"
}
],
"result": "success",
"timing": 792.5
}
|
Command: |
|