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.

Search Vocabulary

Search through the controlled vocabulary.

Usage Information

Command:

vocabulary

Parameters:

term_id: Integer optional

Term ID, if known. If given a term id, that vocabulary term is directly returned.

query_string: String

Search string to find in the vocabulary list

type: String

Type of the vocabulary to search, ex: subject, activity, occupation, geo_place, ...

entity_type: Integer|Null

Entity type ID to filter vocabulary, if known

Return Values:

results: Array of Objects

Array of SNAC Term Objects matching the requested query string

term: Object

SNAC Term Object of the requested term, if term_id was searched

result: String

"success" or "failure" depending on whether the query succeeded.

timing: Float

Number of milliseconds spent to produce the result

Examples:

Direct Term Read

When 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 Term

Being 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
}

back to top

Read Vocabulary Term

Read a particular controlled vocabulary term.

Usage Information

Command:

read_vocabulary

Parameters:

term_id: Integer optional

Term ID, if known. If given a term id, that vocabulary term is directly returned.

type: String optional

Type of the vocabulary to search.

term_value: String optional

The value of the vocabulary to search.

uri: String optional

The unique URI of the vocabulary to search.

Return Values:

term: Object

SNAC Term Object of the requested term

result: String

"success" or "failure" depending on whether the query succeeded.

timing: Float

Number of milliseconds spent to produce the result

Examples:

Read Vocabulary Term

When 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 Term

If 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
}

back to top

Reconcile Against SNAC

Reconcile a given constellation against all constellations in SNAC, returning the top results.

Usage Information

Command:

reconcile

Parameters:

constellation: Object

Constellation object filled with as much information as known about the identity.

Return Values:

reconciliation: Array of Objects

A list of reconciliation objects, including strength of the match, the Constellation matched, and a vector of individual scores that comprise the match strength.

result: String

"success" or "failure" depending on whether the query succeeded.

timing: Float

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
}

back to top

Get User Information

Returns the information for the given user, including information for Constellations locked to the user.

Usage Information

Command:

user_information

Parameters:

user: Object

User object

Return Values:

user: Object

Full user object with name, affiliation Constellation, role and privilege list

groups: Array of Objects

List of Group objects to which the user belongs

messages: Array of Objects

Unread messages sent to this user

editing: Array of Objects

Simplified objects of {id, version, nameEntry} of the Constellations this user has checked out

editing_lock: Array of Objects

Simplified objects of {id, version, nameEntry} of the Constellations this user is currently editing (locked)

review: Array of Objects

Simplified objects of {id, version, nameEntry} of the Constellations sent for review to any reviewer

review_lock: Array of Objects

Simplified objects of {id, version, nameEntry} of the Constellations sent for review (locked) to this user

recent: Array of Objects

Simplified objects of {id, version, nameEntry} of the Constellations recently published by this user

timing: Float

Number of milliseconds spent to produce the result

Examples:

Get Current User Information

Query:
{
    "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
    }
}

back to top

Insert New Constellation

Insert a new Constellation into SNAC. The Constellation must have the operation flags set to "insert".

Usage Information
Permissions Required: Edit

Command:

insert_constellation

Parameters:

apikey: String

Valid API Key

constellation: Object

Full Constellation object

message: String optional

A commit message

Return Values:

constellation: Object

Full Constellation object with current id and version numbers

result: String

"success" or "failure" depending on whether the query succeeded.

timing: Float

Number of milliseconds spent to produce the result

Examples:

Insert a simple Constellation

Inserting 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
}

back to top

Insert And Publish New Constellation

Insert a new Constellation into SNAC. The Constellation must have the operation flags set to "insert".

Usage Information
Permissions Required: Publish

Command:

insert_and_publish_constellation

Parameters:

apikey: String

Valid API Key

constellation: Object

Full Constellation object

message: String optional

A commit message

Return Values:

constellation: Object

Full Constellation object with current id and version numbers

result: String

"success" or "failure" depending on whether the query succeeded.

timing: Float

Number of milliseconds spent to produce the result

Examples:

Insert a simple Constellation

Inserting 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
}

back to top

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.

Usage Information
Permissions Required: Edit

Command:

update_constellation

Parameters:

apikey: String

Valid API Key

constellation: Object

Full Constellation object, with current ids and versions (the result of calling edit)

message: String optional

A commit message

Return Values:

constellation: Object

Full Constellation object with current id and version numbers

result: String

"success" or "failure" depending on whether the query succeeded.

timing: Float

Number of milliseconds spent to produce the result

Examples:

Update a simple Constellation

Update 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
}

back to top

Publish Constellation

Publishes the given Constellation in SNAC. This does not make any updates to the Constellation data in SNAC.

Usage Information
Permissions Required: Publish

Command:

publish_constellation

Parameters:

apikey: String

Valid API Key

constellation: Object

Full Constellation object, with current ids and versions (the result of calling edit)

message: String optional

A commit message

Return Values:

constellation: Object

Full Constellation object with current id and version numbers

result: String

"success" or "failure" depending on whether the query succeeded.

timing: Float

Number of milliseconds spent to produce the result

Examples:

Publish a Constellation

When 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
}

back to top

Unlock Constellation

Drops the lock on the given Constellation from "currently editing" down to simply locked to the user.

Usage Information
Permissions Required: Edit

Command:

unlock_constellation

Parameters:

apikey: String

Valid API Key

constellation: Object

Constellation object with current ID and Version number

Return Values:

constellation: Object

Unlocked Constellation object with current id and version numbers

result: String

"success" or "failure" depending on whether the query succeeded.

timing: Float

Number of milliseconds spent to produce the result

Examples:

Unlock a Constellation

When 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
}

back to top

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.

Usage Information
Permissions Required: Edit

Command:

review_constellation

Parameters:

apikey: String

Valid API Key

reviewer: Object optional

User object of the intended reviewer

constellation: Object

Constellation object with at least current ID and Version

message: String optional

A message for the reviewer

Return Values:

constellation: Object

Full Constellation object with current id and version numbers

result: String

"success" or "failure" depending on whether the query succeeded.

timing: Float

Number of milliseconds spent to produce the result

Examples:

Sending for Review

When 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
}

back to top

Delete Constellation

Deletes the given Constellation from SNAC. This does not make any updates to the Constellation data in SNAC before deleting.

Usage Information
Permissions Required: Delete

Command:

delete_constellation

Parameters:

apikey: String

Valid API Key

constellation: Object

Constellation object to delete with at least current ID and Version

Return Values:

constellation: Object

Full Constellation object deleted

result: String

"success" or "failure" depending on whether the query succeeded.

timing: Float

Number of milliseconds spent to produce the result

Examples:

Delete a Constellation

When 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
}

back to top

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.

Usage Information
Permissions Required: Change Locks

Command:

reassign_constellation

Parameters:

apikey: String

Valid API Key

constellation: Object

Constellation object to assign, with at least current ID and Version

to_user: Object

User object for the user to whom the Constellation should be assigned

Return Values:

constellation: Object

Full Constellation object with current id and version numbers

result: String

"success" or "failure" depending on whether the query succeeded.

timing: Float

Number of milliseconds spent to produce the result

Examples:

Reassign Constellation

When 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
}

back to top

List Recently Published

Returns a list of the most recently published Constellations in SNAC.

Usage Information

Command:

recently_published

Return Values:

constellation: Array of Objects

Simplified Constellation objects {id, ark, nameEntry} of the recently published Constellations

result: String

"success" or "failure" depending on whether the query succeeded.

timing: Float

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
}

back to top

List Random Constellations

Returns a random subset of the Constellations in SNAC.

Usage Information

Command:

random_constellations

Return Values:

constellation: Array of Objects

Simplified Constellation objects {id, ark, nameEntry} of random Constellations

result: String

"success" or "failure" depending on whether the query succeeded.

timing: Float

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
}

back to top

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.

Usage Information
Permissions Required: Change Locks

Command:

list_constellations

Parameters:

apikey: String

Valid API Key

status: String optional

Status of Constellations to return. Currently supported: "published" (default) and "needs review"

Return Values:

results: Array of Objects

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
}

back to top

Get Constellation History

Returns the edit history of the given Constellation.

Usage Information

Command:

constellation_history

Parameters:

constellationid: Integer

Constellation ID

Return Values:

constellation: Object

Full current Constellation Object

history: Array of Objects

List of history objects, in reverse order, describing what has happened to the Constellation through the current version.

timing: Float

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
}

back to top

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}.

Usage Information

Command:

download_constellation

Parameters:

constellationid: Integer optional

Constellation ID for Constellation to read

version: Integer optional

Version of the Constellation to read

type: String optional

What type of file to return: constellation_json or eac_cpf.

arkid: String optional

ARK ID for Constellation to read, of the form 'http://n2t.net/ark:/99166/xxxxxxxx'

Return Values:

file: Object

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
}

back to top

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.

Usage Information

Command:

constellation_list_maybesame

Parameters:

apikey: String optional

Valid API Key

constellationid: Integer

Constellation ID

Return Values:

mergeable: Boolean

Boolean value denoting whether the Constellations can be merged by this user

constellation: Object

Summary Constellation Object of the requested Constellation

maybe_same: Array of Objects

Array of objects, each containing a "mergeable" flag and a Constellation Object of the Constellation asserted to be the maybe the same.

timing: Float

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
}

back to top

Add Maybe-Same Constellation Assertions

Makes a maybe-same assertion between the constellations specified.

Usage Information

Command:

constellation_add_maybesame

Parameters:

apikey: String

Valid API Key

assertion: String

User's assertion statement about the similarity of these Constellations

constellationids: Array of Integers

2 or more Constellation IDs to assert as maybe_same

Return Values:

result: String

"success" or "failure" depending on whether the merge succeeded.

timing: Float

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
}

back to top

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.

Usage Information

Command:

constellation_diff

Parameters:

constellationid1: Integer

Constellation ID for one Constellation to compare

version1: Integer optional

Constellation Version to compare. If not set, it will compare the published version.

constellationid2: Integer

Constellation ID for the other Constellation to compare

version2: Integer optional

Constellation Version to compare. If not set, it will compare the published version.

Return Values:

constellation1: Object

Constellation object containing only data distinct to the first Constellation

constellation2: Object

Constellation object containing only data distinct to the second Constellation

intersection: Object

Constellation object containing only data shared by both Constellations

mergeable: Boolean

Boolean value denoting whether these two Constellations can be merged by this user

Examples:

Diff

Query:
{
    "command": "constellation_diff",
    "apikey": "...",
    "constellationid1": 123456,
    "constellationid2": 987654
}
Response:
{
    "result": "success",
    "constellation1": {
        "...": "..."
    },
    "constellation2": {
        "...": "..."
    },
    "intersection": {
        "...": "..."
    },
    "mergeable": true
}

back to top

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.

Usage Information
Permissions Required: Merge

Command:

constellation_diff_merge

Parameters:

apikey: String

Valid API Key

constellationid1: Integer

Constellation ID for one Constellation to compare

constellationid2: Integer

Constellation ID for the other Constellation to compare

Return Values:

constellation1: Object

Constellation object containing only data distinct to the first Constellation

constellation2: Object

Constellation object containing only data distinct to the second Constellation

intersection: Object

Constellation object containing only data shared by both Constellations

mergeable: Boolean

Boolean value denoting whether these two Constellations can be merged by this user

Examples:

Successful Mergeable Diff

If 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
}

back to top

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.

Usage Information

Command:

constellation_merge

Parameters:

apikey: String

Valid API Key

constellationids: Array of Integers

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.

constellation: Object

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:

constellation: Object

Full Constellation object with current id and version numbers

result: String

"success" or "failure" depending on whether the merge succeeded.

timing: Float

Number of milliseconds spent to produce the result

Examples:

Merge three Constellations

If 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
}

back to top

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.

Usage Information

Command:

constellation_auto_merge

Parameters:

apikey: String

Valid API Key

constellationids: Array of Integers

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:

constellation: Object

Full Constellation object with current id and version numbers

result: String

"success" or "failure" depending on whether the merge succeeded.

timing: Float

Number of milliseconds spent to produce the result

Examples:

Auto-merge three Constellations

If 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
}

back to top

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.

Usage Information

Command:

read

Parameters:

constellationid: Integer optional

Constellation ID for Constellation to read

version: Integer optional

Version of the Constellation to read

type: String optional

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.

arkid: String optional

ARK ID for Constellation to read, of the form 'http://n2t.net/ark:/99166/xxxxxxxx'

sameas: String optional

One of the Constellation's external links, for example 'http://en.wikipedia.org/wiki/Harriet_Tubman'

Return Values:

result: String

"success" if one Constellation is returned, "success-notice" if there is a special return.

message: Object

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.

constellation: Object|Array of Objects

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.

maybesame_count: Integer

Number of other Constellations in SNAC listed as maybe-the-same as this one.

timing: Float

Number of milliseconds spent to produce the result

Examples:

Read a Constellation

By 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
}

back to top

Edit Constellation

Check out the Constellation for editing.

Usage Information
Permissions Required: Edit

Command:

edit

Parameters:

apikey: String

Valid API Key

constellationid: Integer

Constellation ID for Constellation to edit

Return Values:

review_note: String

Reviewer's note, if set by another user.

constellation: Object|Array of Objects

Full Constellation object with current id and version numbers, ready for editing. Those id/version values must be present with future update queries.

timing: Float

Number of milliseconds spent to produce the result

Examples:

Edit a Constellation

Query:
{
    "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
}

back to top

Search for a Constellation, returning a list of possible matches.

Usage Information

Command:

search

Parameters:

term: String

Search term to query against SNAC

start: Integer

Position in the results to start. Begin with 0

count: Integer

Number of results to return

entity_type: String optional

The entity type of the identity to search (person, corporateBody, family)

biog_hist: Boolean optional

Whether or not to search biographical histories for the search term

facets: Object of String Arrays optional

Facets to use in searching.

search_type: String optional

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:

results: Array of Objects

Simplified Constellation objects {id, ark, nameEntry} of random Constellations

aggregations: Object of String Arrays

List of facets that are included in the current search results

term: String

Search term to query against SNAC

count: Integer

Number of results returned in this request

total: Integer

Number of total search results

page: Integer

Page number of results based on total and count

pagination: Integer

Number of total pages of results based on total and count

search_type: String

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.

timing: Float

Number of milliseconds spent to produce the result

Examples:

Basic Search

A 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
}

back to top

Browse Constellations

Given a query name heading, returns the surrounding matching Constellations (in alphabetical order).

Usage Information

Command:

browse

Parameters:

term: String

Search term to query against SNAC

entity_type: String optional

The entity type of the identity to search (person, corporateBody, family)

position: String optional

Whether the "requested" term in the browse list should be in the "middle" of the list, "before", or "after".

icid: String optional

Constellation ID if needed to distinguish between identical names in the response list

Return Values:

results: Array of Objects

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.

result: String

"success" or "failure" depending on whether the query succeeded.

timing: Float

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
}

back to top

Insert Resource

Given a Resource, inserts it into SNAC's resource cache.

Usage Information
Permissions Required: Edit

Command:

insert_resource

Parameters:

resource: Object

Resource object to write to SNAC, with "operation" set to "insert".

apikey: String

Valid API Key

Return Values:

resource: Object

Full resource object as written to SNAC

result: String

"success" or "failure" depending on whether the query succeeded.

timing: Float

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
}

back to top

Read Resource

Read the entire Resource from SNAC's resource cache.

Usage Information

Command:

read_resource

Parameters:

resourceid: Integer

The resource ID from SNAC to read

Return Values:

resource: Object

Full resource object from SNAC

timing: Float

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
}

back to top

Searches the resource cache in SNAC. Returns the top matches.

Usage Information

Command:

resource_search

Parameters:

term: String

Search term to query against the SNAC resource cache.

count: Integer optional

Number of results to return

Return Values:

results: Array of Objects

List of matching Resource objects from SNAC

total: Integer

Number of total search results

page: Integer

Page number of results based on total and count

pagination: Integer

Number of total pages of results based on total and count

timing: Float

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
}

back to top

Delete Resource

Deletes a given resource and all its relationships

Usage Information
Permissions Required: ViewAdminDashboard

Command:

delete_resource

Parameters:

resourceid: String

ID of the resource to delete

Return Values:

result: String

"success" or "failure" depending on whether the query succeeded.

timing: Float

Number of milliseconds spent to produce the result

Examples:

Query:
{
    "command": "delete_resource",
    "resourceid": "76763300",
    "apikey": "..."
}
Response:
{
    "result": "success"
}

back to top

Elastic Search Query

Search through the Constellation indexes using Elastic Search syntax.

Usage Information

Command:

elastic

Parameters:

query: Object

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.

size: Integer optional

Number of results to return

from: Integer optional

Starting point in the results, 0-based

Return Values:

results: Array of Objects

Full results directly from Elastic Search

timing: Float

Number of milliseconds spent to produce the result

Examples:

Basic Elastic Search Query

A 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
}

back to top

Parse EAC-CPF XML to Constellation (Pre-Alpha)

Parses a given EAC-CPF file into a Constellation JSON object using the SNAC profile.

Usage Information

Command:

parse_eac

back to top

Add external links to a constellation

Links a constellation to an external identity on sites such as Wikipedia, VIAF, etc.

Usage Information

Command:

add_sameas

Parameters:

apikey: String

Valid API Key

constellationid: Integer

Constellation ID

sameas_uris: Array

An array of URIs to link this constellation to.

Examples:

Add sameAs links

Checks 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
}

back to top

Get Holdings

Get an array of resources held by a Holding Repository

Usage Information

Command:

get_holdings

Parameters:

constellationid: Integer

Constellation ID

Examples:

Get Holdings

Get 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
}

back to top

Shared Resources

Get an array of resources related to both constellations

Usage Information

Command:

shared_resources

Parameters:

icid1: Integer

Constellation ID

icid2: Integer

Constellation ID

Examples:

Shared Resources

Get 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
}

back to top

Usage Information

Command:

merge_resource

back to top