Using Search

Research outputs can be searched and filtered by ERA Round, Output Type, Institution or by ERA Journal Id. The searching mechanism is based on Full-text queries that perform linguistic searches against Research Output data stored at ARC. Full-text queries can include simple words and phrases or multiple forms of a word or phrase. A full-text query returns any results that contain at least one match. The following filters can be used to filter the search results. Choose from the options in the select list and press the add (+) button to filter the results.

  • ERA Round - filter the result by ERA Round.
  • Type - filter the result by one or more Research Output Types
  • Institution - typeahead search by name or short name and select one or more institutions to filter the result.
  • ERA Listed Journal - typeahead search by title or ERA Journal ID and select one or more listed journals to filter the result.

To undertake a search, enter your search term in the search field. You can enter multiple search terms in this field, for example, you could enter the name of a publisher, a field of research, a university name (shortened versions are acceptable, i.e. ANU for Australian National University). Please note, the search will return results that contain all of the words you have entered (i.e. using the ’AND’ connector).

Note: Search will attempt fuzzy matching of the search terms. E.g. singular/plural/uppercase/lowercase/related words (stemming). All searches ignore upper/lowercase.

The following are some examples and instructions on refining your free-text search.

Query Description
Quantum Computing
Returns entries that have occurrences of words like 'Quantum' AND 'Computing'
+Nuclear or "Nuclear"
Putting '+' before the search term or enclose the term in double quotes will search for an exact match. Returns entries that contain exactly the term Nuclear, no plurals or other fuzzy matches.
"Quantum Computing"
Putting a phrase inside quotes will return entries that contain exact occurrences of phrase like 'Quantum Computing'.
"Quantum Computing" +USA
Returns entries that have exact occurrences of phrases like 'Quantum Computing' AND exact match of the word 'USA'.
Physics -Nuclear
Putting '-' in front of a word, excludes it from your search. This will return records that contain Physics but not Nuclear.
Note: it is not valid to have '-' as the first element in a search
Australia -"New Zealand"
Returns entries that have occurrences of word like Australia AND NOT 'New Zealand'.
Nuclear OR Physics
Returns entries that have at least one of Nuclear or Physics.
<health significant challenge>
Returns search entries with the three terms health, significant and challenge in close proximity. Proximity search looks for entries where the search terms are near to each other in the result text.
Cryst*
Trailing wildcard (*) - putting a '*' at the end of a search term searches for words that start with the search term fragment. This example will return entries containing crystal or crystallography or crystalline or crystallisation, etc.
(health child OR (military -profile) 
OR <mother daughter>)
Brackets '(' and ')' can be used in combination with 'AND', 'OR' and other search features to search for complex conditions. This example returns entries that have terms Like 'health' AND Like 'child' OR Like 'military' AND NOT Like 'profile' OR (mother proximity to daughter)
Note: unmatched brackets will cause phrase search fall back.
climate {}$#%^~,1 a the then
Common letters/words such as 'a', 'the', 'then', 'it', 'as', 'of', numbers, punctuations are excluded from search terms. In this example, the search will return entries that match the term climate (equivalent to search term climate)
Note: any searches with special characters, punctuation or letters other than English will need to be enclosed in double quotes, otherwise the search may not work as expected and may return no results.

For advanced searches, free-text query can also be combined with expression filters. The expression filter begins with the '=>' key. Expression filters can be combined with operators 'AND' and 'OR'. Parentheses '(...)' can also be used to enclose sub queries to form a more complex query.

Syntax: <search text> => <filter queries>
The following are the supported expression filters with examples...
Expression Filter Description
era-round
Filters results by ERA round.
=> era-round="ERA 2018"
Gets Results having word like Australia filtered by ERA Round.
Australia => era-round="ERA 2018" 
institution-name
Filters results by institution full name.
=> institution-name="victoria university"
institution-short-name
Filters results by institution short name.
=> institution-short-name="VIC"
research-output-type
Filters results by research output type.
=> research-output-type="Book"
reference-year
Filters results by reference year.
=> reference-year="2017"
era-journal-id
Filters results by ERA Journal ID.
=> era-journal-id="1"

Calling The API

The DataPortal API for ERA Research Outputs follows the JASON API Specification (v1.0). The API supports Pagination, Filters and error handling as per the specification. Sparse Fieldsets and Sorting are not supported at this stage.

The ERA Research Outputs API data is provided in a paginated format. Clients can access this API by specifying a Page Size of up to a maximum of 100 records. The following is an example the URL format :

https://dataportal.arc.gov.au/ERA/API/research-outputs?page[size]=20&page[number]=1&filter=[SEARCH TEXT]=>(era-round="[ERA ROUND]") AND(institution-short-name="[INSTITUTION SHORT NAME]" OR institution-name="[INSTITUTION NAME]") AND(research-output-type="[RESEARCH OUTPUT TYPE]")

Where

  • SEARCH TEXT - free text word or phrase to search on. Optional filters can be added to SEARCH TEXT using the separator '=>'
  • ERA ROUND - results are filtered by ERA round
  • INSTITUTION NAME - results are filtered by institution name.
  • INSTITUTION SHORT NAME - results are filtered by institution short name
  • RESEARCH OUTPUT TYPE - results are filtered by research output type

The API URL components must be encoded before calling the API. The following is an example of an encoded URL.

https://dataportal.arc.gov.au/ERA/API/research-outputs?page%5Bsize%5D=20&page%5Bnumber%5D=1&filter=australia%20%3D%3E%20(institution-short-name%3D%22ANU%22%20OR%20institution-short-name%3D%22MON%22)%20AND(research-output-type%3D%22Book%22)

The following is a snippet of a paginated JSON API research outputs that has one research output per page.


{
    "meta": {
        "requested-page-number": 1,
        "requested-page-size": 1,
        "actual-page-size": 1,
        "total-pages": 283824,
        "total-size": 567647,
        "search-description": null
    },
    "links": {
        "self": "https://dataportal.arc.gov.au/ERA/API/research-outputs?page%5Bnumber%5D=1&page%5Bsize%5D=1",
        "first": "https://dataportal.arc.gov.au/ERA/API/research-outputs?page%5Bnumber%5D=1&page%5Bsize%5D=1",
        "last": "https://dataportal.arc.gov.au/ERA/API/research-outputs?page%5Bnumber%5D=283824&page%5Bsize%5D=1",
        "prev": "https://dataportal.arc.gov.au/ERA/API/research-outputs?page%5Bnumber%5D=1&page%5Bsize%5D=1",
        "next": "https://dataportal.arc.gov.au/ERA/API/research-outputs?page%5Bnumber%5D=2&page%5Bsize%5D=1"
    },
    "data": [
        {
            "type": "research-outputs",
            "id": "1142103",
            "attributes": {
                "era-round": "ERA 2018",
                "institution": "Queensland University of Technology",
                "research-output-type": "Book",
                "title": "Stormwater management: An introduction to Green Gully",
                "outlet": "Nova Science Publishers",
                "reference-year": 2011,
                "doi": null,
                "place-of-publication": "United States",
                "other-details": {
                    "extent": "134",
                    "isbn": "978-1-61209-311-6",
                    "publisher": "Nova Science Publishers",
                    "edition": null
                }
            }
        }
    ]
}

In the snippet above, the meta attribute has the information related to page size, page number, total results and search description. The search description is in Abstract Syntax Tree (AST) format. The links attribute has navigation links to other pages and the data attribute has the collection of research outputs data.

Clients can fetch a maximum of 100 results per page and then keep navigating the results of subsequent pages by following the navigation links. They can also get the desired results using filters and search text as described in the Using Search section. The API also supports Free-Text search operations like AND, OR, NOT. Words like ‘as’, ‘the’, ‘if’, ‘of’, etc may be ignored for a more predictable result, however phrases within a double quote will return exact matches.

Troubleshooting

No relevant data in the response


{
    "meta":{...}
    "links": {...}
    "data": []
}

                    

For a specified search, there is no data.

A 'Failed/Unexpected/Unauthorized' response


{
    "links": {
        "self": "https://dataportal.arc.gov.au/ERA/API/research-outputs?page%5Bsize%5D=0&page%5Bnumber%5D=1&filter=titlenotfound"
    },
    "errors": [
        {
        "id": "500InternalServerError",
        "status": "InternalServerError",
        "code": "500",
        "title": "SqlException",
        "detail": "The number of rows provided for a FETCH clause must be greater then zero."
        }
    ]
}

{
    "links": {
        "self": "https://dataportal.arc.gov.au/ERA/API/research-outputs"
    },
    "errors": [
        {
            "id": "401Unauthorized",
            "status": "Unauthorized",
            "code": "401",
            "title": "UnauthorizedAccessException",
            "detail": "..."
        }
    ]
}

A failed/unexpected/unauthorised response will occur when :

  • The URL has invalid attribute values
  • The client issues a bad request
  • The client is trying to access unauthorized URL or data.
  • The client is blocked by ARC