Legacy Vocabulary Service API

Legacy Vocabulary Service API Documentation

ANDS continues to provide this legacy API only in order to support the resolution of certain URLs as redirected from purl.org, and this documentation page is of historical value only. The concepts of the RIF-CS vocabulary, and ANDS’s packaging of the ANZSRC-FOR and ANZSRC-SEO vocabularies, have URLs which begin http://purl.org/... that are configured to resolve to this API, and because of ongoing issues at purl.org, ANDS is currently unable to modify the redirections to make use of new vocabulary services.

Research Vocabularies Australia is ANDS’s public vocabulary service, and it supports an expanded Linked Data API which (with only very minor changes) is compatible with this one, but also makes available many more vocabularies. Please refer to the new Linked Data API documentation.

The remainder of this page is the legacy documentation …

The ANDS Controlled Vocabularies service allows research organisations to publish and query “controlled vocabularies” relating to their research datasets. The use of controlled vocabularies in the description of research data collections improves access, findability and reuse of research data.

ANDS uses a customised instance of SISSvoc 3 to host a number of commonly used controlled vocabularies. The Vocabulary Service API allows developers to integrate with the vocabulary service using HTTP and a variety of data representations (including XML, JSON and RDF).

Example use cases for the service include:

  • Populate select lists and menus enabling users to classify and link data through the use of published and standardised terminologies
  • Searching for and resolving information about published terminologies
  • Providing a common, globally resolveable identifier for terms and concepts

For some of these use cases, you may also consider using the easy-to-implement ANDS Vocabulary Widget.

What does a vocabulary look like?

Vocabularies hosted by the ANDS Vocabulary Service are modelled using the Simple Knowledge Organization System (SKOS) and expressed as Resource Description Framework (RDF) triples.

Each concept represented in a vocabulary is identified by a unique URI. These URIs can be passed as a parameter to a number of the services to retrieve specific concepts or sets of concepts.

The following diagram illustrates the simple hierarchy implied by the service calls:

skos_concept_diagram

ANDS Vocabulary Service

Supported Vocabularies

Vocab Key Title More Information
rifcs15 Registry Interchange Format v1.5 – Collections and Services (RIF-CS) Schema Vocabulary Vocab Catalogue EntryRIF-CS vocabulary types
anzsrc-for 1297.0 – Australian and New Zealand Standard Research Classification (ANZSRC), 2008 Vocab Catalogue EntryAustralian Bureau of Statistics
anzsrc-seo 1297.0 – Australian and New Zealand Standard Research Classification (ANZSRC), 2008 – Socio-Economic Objective Codes Vocab Catalogue EntryAustralian Bureau of Statistics

Research Organisations who are looking for a service to host their own controlled vocabularies should contactservices@ands.org.au.

Resource URL

http://researchdata.ands.org.au:8080/vocab/api/{vocab key}/{service call}

  • This API is a RESTful Web Service. Simply replace the blue parameters with the appropriate values and issue a HTTP GET request.
  • Replace:
    • {vocab key} with the key of the supported vocabulary you are interested in.
    • {service call} with some combination of the service parameters listed below.
    • Note: all parameter values (including URIs embedded as parameters) must be URL-encoded.

Service Calls & Example Usage

The Vocabulary Service also has built-in documentation. See the /meta/ service call.

Core Services

Retrieve a listing of all the concepts contained within a vocabulary.

Examples:

Optionally, pass ?scheme=... to restrict to concepts from a specific concept scheme (identified by URI)

Retrieve a listing of all the concept schemes contained within a vocabulary.

Examples:

 

Retrieve a listing of all the concepts where the provided text:

  • Is contained within the rdfs:label, skos:prefLabel or skos:altLabel properties of a concept, or
  • Is contained within the ‘resource URI’ of a the concept, or
  • Exactly matches the ‘notation’ property of the concept.

Examples:

This query is case insensitive.

Retrieve a listing of all the concepts where the provided text exactly matches the skos:prefLabel orskos:altLabel properties of the concept.

Examples:

This query is case sensitive.

Hierarchy-oriented Services

Retrieve a listing of all the top concepts contained within a vocabulary.

Examples:

Also supports restricting results to those contained within a concept scheme by appending ?scheme=...

Retrieve a listing of all the concepts in a vocabulary, which are the children of (one step lower in the hierarchy), concepts with a label exactly matching the provided text.

Examples:

Also supports matching on label matches by using ?anylabel=... in place of ?uri=...

Retrieve a listing of all the concepts in a vocabulary, which are the parents of (one step higher in the hierarchy) a concept identified by the specified URI.

Examples:

Also supports matching on label matches by using ?anylabel=... in place of ?uri=...

Retrieve all concepts narrower than a specified concept, down to and including the last concepts in each possible path.

Examples:

Only supported in certain vocabularies (currently: anzsrc-for & anzsrc-seo)

 

Retrieve all concepts broader than a specified concept, up to and including the top concepts in each possible path.

Examples:

Only supported in certain vocabularies (currently: anzsrc-for & anzsrc-seo)

Collection Services

Retrieve a listing of all the concept collections contained within a vocabulary. Collections are used by vocabulary managers to group concepts that share something in common, under a specific label.

Examples:

Only supported in certain vocabularies (currently: rifcs15)

Response Format

  • Responses from this service can be returned in a variety of popular formats. By default, the service will respond with a HTML page.
  • To request a specific format, append the format suffix to the service call. Valid formats include:
Format Suffix Description Example Usage
.json Response in JSON format concepts/inCollection.json?uri=...
.xml Response in XML format concepts/topConcepts.xml
.rdf Response in RDF/XML format collections.rdf?scheme_uri=...
.ttl Response in Turtle format conceptschemes.ttl
.html
(default)
Response in HTML format /concepts.html/ or /concepts/

Leave a Reply

Your email address will not be published. Required fields are marked *

8 − three =