getMetadata API

getMetadata API Documentation

getRIFCS-architecture

The getMetadata API provides access to the contents of the Search Index underpinning the ANDS Collections Registry. This effectively offers open access to the same infrastructure which powers the search and browsing capabilities in Research Data Australia.

Using this powerful API, your application can perform complex search queries, retrieving the indexed data values as well as performing aggregations and simple spatial searches. This API also includes many of the extended metadata fields available through the getExtRif service.

This service is different to the other Collection Registry APIs in that it principally returns a JSON representation of the metadata fields and not the original RIF-CS XML.
This allows you to easily restrict what data fields you want to retrieve in order to optimise your application’s performance.

Service Usage

Before you start! To use this service, institutions or individuals must register for a free API key.

Resource URL

http://researchdata.ands.org.au/registry/services/{YOUR API KEY}/getMetadata?{params}

  • This API is a RESTful Web Service. Simply replace the blue parameters with the appropriate values and issue a HTTP GET request.
  • Replace {YOUR API KEY} with the key your organisation registered (no API key? register for free)
  • Replace {params} with some combination of the parameters below. Note: all parameter values must be URL-encoded.
  • By default, results are limited to 10 records per request. Use the start and rows parameters to step through additional results.

Service Parameters

Useful Note These parameters have the same meaning as defined by SOLR Common Query Parameters (SOLR enterprise search server).

Parameter Description Example Usage
q The q parameter is normally the main query for the request.

All values of q must be URL-encoded. It is also recommended that string values are surrounded by quotes.

By default, the field seperator is “OR” unless “AND” is explicitly specified (see example usage #4).

1. Matching all records (i.e. unrestricted search):
q=*:*2. Matching records based on a particular field:
q=class:(collection)3. Matching multiple field values (OR):
q=class:(collection OR party)

4. Matching on multiple fields (AND):
q=class:(collection) AND group_search("Monash")

5. Wildcard searching on string fields:
q=title_search:(*survey*)

Wait! How do I know what fields to search? See Indexed Fields

fl Restricts the metadata fields which are returned by the search query.

By default, the following fields are returned:
id,key,slug,display_title,class

1. Select only keys and record titles:
?fl=key,display_title2. Select all information about related objects:
?fl=key,related_object_*2. Select all fields which are indexed:
?fl=*
sort Sorting can be done on any indexed field which only has single values. Sort can be either: desc or asc.

Note: Fields which are indexed as string or integers are sortable. Other field types may produce unexpected results.

1. Sort based on key in ascending order:
q=*:*&sort=key asc2. Sort based on update time in descending order (most recent first):
q=key:*:*&sort=update_timestamp desc

start
rows
This parameter is used to paginate results from a query.

When specified, it indicates the offset in the complete result set for where the set of returned documents should begin and end.

By default, results start at 0 with 20 rows displayed. That is, by default only 20 rows are displayed in response to a search query.

1. Display the first 20 records with a key starting AODN:

q=key:AODN*

2. Display the next 20 records with a key starting AODN:

q=key:AODN*&start=20

3. Display 100 records starting from number 1000:

q=*:*&start=1000&rows=100


facet
facet.fieldfacet.mincount
Faceting mode is analogous to a GROUP BY statement in SQL.

When specified, faceting mode will retrict the resultset based on your query and then display the field value
and count of records matching that field value.

1. Display the number of records for each group, where the group has 10 or more records.

?facet=on&facet.field=group&facet.mincount=10

2. Display the number of records for each group (collections only)

?facet=on&facet.field=group&q=class:(collection)

Response Format

  • By default, responses from this service are returned in JSON format which is almost identical to the SOLR JSON Response Writer. The service can also return a response in XML format by replacing /getMetadata/ with /getMetadata.xml/ in the request URI.
  • If the query was malformed or invalid, the service will return an error response in the content. The service does not currently support HTTP status headers.

Common Questions

Consult the Indexed Fields List to see what fields you can search against.
A good question! Some of the fields available to search don’t actually exist in the RIF-CS schema and for some use cases, knowing what their values might be can be quite tricky.

Example Usage

Return collection records from a particular group/organisation

Return metadata for 3 records of class “collection” which have the group attribute “Australian Ocean Data Network”:

  • Service Response:
    {
    status: "success",
    message: {
    numFound: 30890,
    start: 0,
    docs: [
    {
    slug: "aims-weather-station-data-cleveland-bay-platform-rain-from-03-jul-1990",
    key: "AODN:c9cb7389-7af1-4e0a-8c95-6f295f1cec1e",
    id: "128152",
    display_title: "AIMS Weather Station Data - Cleveland Bay Platform - From 03 Jul 1990",
    class: "collection"
    },
    {
    slug: "temperature-logger-data-at-penguin-is-east-from-15-may-2012",
    key: "AODN:147b75a3-be17-4c7f-b12d-dbda75446fa1",
    id: "128153",
    display_title: "Temperature Logger Data at Penguin Is East, From 15 May 2012 ",
    class: "collection"
    },
    {
    slug: "assessing-habitat-damage-caused-by-the-grounding-of-the-shen-neng-1-on-douglas",
    key: "AODN:2bf0e568-935d-42fd-9e8b-d946e308d8ba",
    id: "128154",
    display_title: "Assessing habitat damage caused by the grounding of the Shen Neng 1 on Douglas Shoal, southern Great Barrier Reef, using towed video (Towvid)",
    class: "collection"
    }
    ]
    }
    }

Displaying all metadata about a particular record

Return all the indexed metadata about a particular collection:

  • Service Response:
    {
    status: "success",
    message: {
    numFound: 1,
    start: 0,
    docs: [
    {
    slug: "aims-weather-station-data-cleveland-bay-platform-rain-from-03-jul-1990-to-21-oct-1992",
    key: "AODN:c9cb7389-7af1-4e0a-8c95-6f295f1cec1e",
    data_source_key: "acdata.unsw.edu.au",
    status: "PUBLISHED",
    originating_source: "http://www.aims.gov.au/adc",
    id: "128152",
    data_source_id: "135",
    group: "Australian Ocean Data Network",
    s_group: "Australian Ocean Data Network",
    display_title: "AIMS Weather Station Data - Cleveland Bay Platform Rain - From 03 Jul 1990 To 21 Oct 1992",
    list_title: "AIMS Weather Station Data - Cleveland Bay Platform Rain - From 03 Jul 1990 To 21 Oct 1992",
    simplified_title: "AIMS Weather Station Data - Cleveland Bay Platform Rain - From 03 Jul 1990 To 21 Oct 1992",
    description_value: [
    "This data set was collected by weather sensors deployed on the AIMS Weather Station site Cleveland Bay .<br /> <br /> Deployment Information for Rain<br /> Data Interval: From 03 Jul 1990 Through 21 Oct 1992<br /> Deployment Location: Cleveland Bay Platform<br /> Latitude: -19.15583 - Longitude: 146.88116",
    "Attribution 3.0 Australia",
    "Format for citation of data sourced from the Australian Institute of Marine Science (AIMS) in a list of references is as follows: &quot;Australian Institute of Marine Science. [year-of-data-download], [Title], [data-access-URL], accessed [date-of-access]&quot;.",
    "Data, products and services from AIMS are provided &quot;as is&quot; without any warranty as to fitness for a particular purpose."
    ],
    description_type: [
    "brief",
    "rights",
    "rights",
    "rights"
    ],
    spatial_coverage_polygons: [
    "146.88116,-19.15583"
    ],
    spatial_coverage_extents: [
    "146.88116 -19.15583"
    ],
    spatial_coverage_centres: [
    "146.88116 -19.15583"
    ],
    spatial_coverage_area_sum: 0,
    subject_value_unresolved: [
    "Oceans - Ocean Temperature - Water Temperature",
    "EARTH SCIENCES - Atmospheric Sciences - Meteorology",
    "0104",
    "01",
    "0105",
    "0103",
    "04",
    "9699"
    ],
    subject_type: [
    "local",
    "local",
    "anzsrc-for",
    "anzsrc-for",
    "anzsrc-for",
    "anzsrc-for",
    "anzsrc-for",
    "anzsrc-for"
    ],
    subject_value_resolved: [
    "Oceans - Ocean Temperature - Water Temperature",
    "EARTH SCIENCES - Atmospheric Sciences - Meteorology",
    "STATISTICS ",
    "MATHEMATICAL SCIENCES",
    "MATHEMATICAL PHYSICS",
    "NUMERICAL AND COMPUTATIONAL MATHEMATICS",
    "EARTH SCIENCES",
    "9699"
    ],
    subject_vocab_uri: [
    "",
    "",
    "http://purl.org/au-research/vocabulary/anzsrc-for/2008/0104",
    "http://purl.org/au-research/vocabulary/anzsrc-for/2008/01",
    "http://purl.org/au-research/vocabulary/anzsrc-for/2008/0105",
    "http://purl.org/au-research/vocabulary/anzsrc-for/2008/0103",
    "http://purl.org/au-research/vocabulary/anzsrc-for/2008/04",
    ""
    ],
    related_object_key: [
    "AODN:adc@aims.gov.au",
    "AODN:adc@aims.gov.au",
    "AODN:adc@aims.gov.au",
    "AODN:adc@aims.gov.au",
    "AODN:adc@aims.gov.au",
    "AODN:adc@aims.gov.au",
    "AODN:reception@aims.gov.au"
    ],
    related_object_id: [
    "127501",
    "128305",
    "127501",
    "128305",
    "127501",
    "128305",
    "127505"
    ],
    related_object_class: [
    "party",
    "party",
    "party",
    "party",
    "party",
    "party",
    "party"
    ],
    related_object_display_title: [
    "Data Manager, AIMS Data Centre",
    "Alongi, Daniel M, Dr",
    "Data Manager, AIMS Data Centre",
    "Alongi, Daniel M, Dr",
    "Data Manager, AIMS Data Centre",
    "Alongi, Daniel M, Dr",
    "Bainbridge, Scott, Mr"
    ],
    related_object_relation: [
    "metadataContact",
    "metadataContact",
    "pointOfContact",
    "pointOfContact",
    "isManagedBy",
    "isManagedBy",
    "custodian"
    ],
    class: "collection",
    type: "dataset",
    s_type: "dataset",
    description: "This data set was collected by weather sensors deployed on the AIMS Weather Station site Cleveland Bay .<br /> <br /> Deployment Information for Rain<br /> Data Interval: From 03 Jul 1990 Through 21 Oct 1992<br /> Deployment Location: Cleveland Bay Platform<br /> Latitude: -19.15583 - Longitude: 146.88116",
    identifier_value: [
    "AODN:c9cb7389-7af1-4e0a-8c95-6f295f1cec1e"
    ],
    identifier_type: [
    "local"
    ],
    _version_: "1448302860324306944",
    update_timestamp: "2013-10-08T05:14:00.268Z"
    }
    ]
    }
    }

 

Leave a Reply

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

seven − six =