Introduction

SCUA Names is a tool for documenting names used by the Libraries in its various digital library systems and collections. The app provides a consistent way of communicating the authorized version of a name and information about the name that is useful for reuse. SCUA Names generates a unique URL for each name that can be used to unambiguously refer to a person, organization, event, building or piece of software. In addition to an HTML page for each name there are a number of other formats available for each record including a MADS XML version and a simple JSON representation. A key feature of SCUA Names is the ability to link to other vocabularies such as the Virtual International Authority File (VIAF), the Library of Congress Name Authority File, or Wikipedia. As time permits, the Libraries will integrate links into name records where appropriate. A set of APIs are provided for integration of this application into other systems. If you have questions or comments about SCUA Names, or if you would like a name added, please contact the Administrator.

Two search modes are available.

Notice there are two modes of searching. The first mode is a traditional search which takes a query and a type, filtering records containing your query in either the authorized name field or the variant field. The second search method is more of an existence lookup of the authorized name. The user should request http://names.library.umass.edu/label/name_string_here. The API will then either return a 302 Found and redirect to the matching record, or a 404 Not Found. This page will first address the 'traditional' search API, then the label API.

Search API

Let's dive right in! The following are various search examples using curl:

    $ curl "http://names.library.umass.edu/search.json?q=joey+liechty"
    [
        {
            "URL": "http://names.library.umass.edu/nm0051457/",
            "id": "nm0051457",
            "name": "joey liechty",
            "type": "Personal"
        }
    ]

    $ curl "http://names.library.umass.edu/search.json?q=abc&q_type=Organization&callback=foo"
    foo([
        {
            "URL": "/nm0000063/",
            "id": "nm0000063",
            "name": "ABC Shop",
            "type": "Organization"
        }
    ])

    $ curl "http://names.library.umass.edu/search.json?q_type=Software"
    [
        {
            "URL": "http://names.library.umass.edu/nm0051455/",
            "id": "nm0051455",
            "name": "Watson",
            "type": "Software"
        },
        {
            "URL": "http://names.library.umass.edu/nm0012345/",
            "id": "nm0012345",
            "name": "Software Foo",
            "type": "Software"
        },
        {
            "URL": "http://names.library.umass.edu/nm0043212/",
            "id": "nm0043212",
            "name": "123 SoftCom",
            "type": "Software"
        }
    ]

    $ curl "http://names.library.umass.edu/search.json?q_type=Software,Organization"
    [
        {
            "URL": "http://names.library.umass.edu/nm0051455/",
            "id": "nm0051455",
            "name": "Watson",
            "type": "Software"
        },
        {
            "URL": "http://names.library.umass.edu/nm0012345/",
            "id": "nm0012345",
            "name": "Software Foo",
            "type": "Software"
        },
        {
            "URL": "http://names.library.umass.edu/nm0043212/",
            "id": "nm0043212",
            "name": "123 SoftCom",
            "type": "Software"
        },
        {
            "URL": "http://names.library.umass.edu/nm0000063/",
            "id": "nm0000063",
            "name": "ABC Shop",
            "type": "Organization"
        }
    ]
                

Search Return Codes

200 OK response:
  • User gave a fully-formed search query which returns a list of results in JSON format.
410 Gone response:
  • User gives a request for a record that had existed, but has since been deleted.
404 Not Found response:
  • User gives a request for a record that does not exist.
403 Forbidden response:
  • User gives a request for a record that exists, but is not public.
302 Redirect response:
  • User requests a record which has been merged with another record.

How can I narrow my search?

Parameters hang off the end of a search request to narrow the results you get in your response and will get you closer to the name you are attempting to lookup.

q: Optional - the text respresentation of the record name you want to search.
q_type: Optional - the text representation of the record type. 5 types are available to filter the search, "Personal", "Organization", "Event", "Building", "Software".
callback: Optional - the text representation of the jsonp callback wrapper.

Label API

The second method of searching is with the label API. The label API is essentially a quick way to determine if an authorized name exists in SCUA Names. The only two responses to this API are a 404 Not Found or a 302 Redirect.

    $ curl "http://names.library.umass.edu/label/joey-not-here"
    No matching term found - authoritative, or variant - for "joey-not-here"

    $ curl -I "http://names.library.umass.edu/label/thisrecordisforsureinthedatabase"
    HTTP/1.0 302 FOUND
    Date: Mon, 25 Feb 2013 22:33:19 GMT
    Server: WSGIServer/0.1 Python/2.7.3
    Content-Type: text/html; charset=utf-8
    Location: http://names.library.umass.edu/nm0000085/
            

Label Return Codes

404 Not Found response:
  • User gives an authorized name that does not exist in the SCUA Names database.
302 Redirect response:
  • User gives an authorized name that does exist in the SCUA Names database. The system redirects to the corresponding record.