Calling The API

The DataPortal API for ERA Outcomes 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 Outcomes API data is provided in a paginated format. Clients can access this API by specifying a Page Size of up to a maximum of 200 records. The following is an example the URL format :

https://dataportal.arc.gov.au/ERA/API/ratings?page[size]=20&page[number]=1&filter=[FILTER_VALUE]

Where

• FILTER_VALUE - filter by Institution Short Name or Field of Research Code

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

https://dataportal.arc.gov.au/ERA/API/ratings?page%5Bnumber%5D=1&page%5Bsize%5D=20&filter=ANU

The following is an example of an encoded URL filtered by Field of Research

https://dataportal.arc.gov.au/ERA/API/ratings?page%5Bnumber%5D=1&page%5Bsize%5D=20&filter=0201

The following is a snippet of a paginated outcomes that has one outcomes record per page.

{
    "meta": {
        "requested-page-number": 1,
        "requested-page-size": 1,
        "actual-page-size": 1,
        "total-pages": 7518,
        "total-size": 7518
    },
    "links": {
        "self": "https://dataportal.arc.gov.au/ERA/API/ratings?page%5Bnumber%5D=1&page%5Bsize%5D=1",
        "first": "https://dataportal.arc.gov.au/ERA/API/ratings?page%5Bnumber%5D=1&page%5Bsize%5D=1",
        "last": "https://dataportal.arc.gov.au/ERA/API/ratings?page%5Bnumber%5D=7518&page%5Bsize%5D=1",
        "prev": "https://dataportal.arc.gov.au/ERA/API/ratings?page%5Bnumber%5D=1&page%5Bsize%5D=1",
        "next": "https://dataportal.arc.gov.au/ERA/API/ratings?page%5Bnumber%5D=2&page%5Bsize%5D=1"
    },
    "data": [
        {
            "type": "ratings",
            "id": "38324",
            "attributes": {
                "institution": {
                    "name": "Australian Catholic University",
                    "short-name": "ACU"
                },
                "field-of-research": {
                    "code": "01",
                    "name": "Mathematical Sciences"
                },
                "outcomes": [
                    {
                        "year": 2010,
                        "value": "NA",
                        "description": "Not assessed due to low volume"
                    },
                    {
                        "year": 2012,
                        "value": "NA",
                        "description": "Not assessed due to low volume"
                    },
                    {
                        "year": 2015,
                        "value": "NA",
                        "description": "Not assessed due to low volume"
                    },
                    {
                        "year": 2018,
                        "value": "NA",
                        "description": "Not assessed due to low volume"
                    }
                ]
            }
        }
    ]
}

In the snippet above, the meta attribute has the information related to page size, page number and total results. The links attribute has navigation links to other pages and the data attribute has the collection of ERA Outcomes.

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