MyHospitals API
On this page
About the API
The MyHospitals application programming interface (API) provides access to a selection of hospital data, allowing you to get up to date hospital data in portable data formats JSON and CSV.
The API is open and free to use. You can interact with the API to consume hospital data and use it in your own software and systems.
Who is the API for?
The MyHospitals API is mainly for software and data specialists, who can use the API to communicate with AIHW machine-to-machine and acquire data. The API is used by AIHW staff, other government agencies, the private sector, and individuals.
The API is only one way to get access to hospital data. You can also access hospital data on the data downloads page, or by using the interactive visualisations on MyHospitals.
What data is available?
The API allows you to make requests from a selection of hospital data. The data is always up to date with the latest releases on MyHospitals. Available data includes:
- Hospital data – Data on elective surgery, emergency department care, admissions, length of stay, available services, and more.
- Multi-level data – Data may be available at multiple levels, from the hospital level to aggregate figures at local hospital network (LHN), state or territory, and national levels. Availability can vary across data collections.
- Geographic data about hospitals – The API offers location data and some mappings for Australian hospitals.
We will continue to load the latest hospital data, and as we continue to develop MyHospitals the API may grow to include more data.
Getting started
Key information for new users
API URL
https://myhospitalsapi.aihw.gov.au/
API calls
To understand and use the MyHospitals API calls:
- Go to the API’s interactive home page and try out the API calls
- Read the API schemas and examples
- Explore the JSON OpenAPI definition of the MyHospitals API
Use the interactive page to test the API. Add filters or change the response format to return the data you are interested in.
To understand the data that is returned by the API calls, look for the schemas at the bottom of the interactive home page, in the documentation, or in the OpenAPI definition. The schemas provide useful details about the data, including descriptions, types, structures, and relationships within the data.
Response format
Most API calls provide a response in machine readable JSON or CSV format. JSON is returned by default, or you can specify JSON or CSV in the HTTP accept header on an API request:
- an accept header value of ‘application/json’ returns JSON
- an accept header value of ‘text/csv’ returns CSV
The JSON responses follow a similar format for all API calls and include metadata information along with the result data. Each JSON response is split into 2 parts:
- result – this contains the data from the API call and matches the format of the response schema for that call
- version_information – this is metadata related to the API call and contains:
- the API version
- the data version
- the date the data was uploaded
- the timestamp of the request
The CSV response format only contains the result information.
Some API calls return downloadable Excel spreadsheets which are structured and formatted in a consistent template.
Versioning
The API version is included within the API URL using the format: /api/{version}/{resource}
The API was developed in line with the National API Design Standards on api.gov.au and each version has been documented according to the OpenAPI 3.0 Specification (formerly known as Swagger) for describing and documenting APIs.
| API version | Status | API definition JSON |
|---|---|---|
| v1 | Current | http://myhospitalsapi.aihw.gov.au/swagger/v1/swagger.json |
| v0 | Deprecated | http://myhospitalsapi.aihw.gov.au/swagger/v0/swagger.json |
Note that v0 of the API is the old version which was available on the previous myhospitals.gov.au website. If you are still using this version, we continue to provide the old endpoints but encourage you to migrate your applications to use the new version of the API.
Authentication
Currently the API is open and free to use, so it requires no authentication. However, this is subject to change and depending on usage an API key system may be implemented in the future.
Availability
While we strive to make the API available for use at any time, availability is not guaranteed. The API may be temporarily disabled for maintenance or other reasons.
Responsiveness
Most API queries are returned within seconds or milliseconds. Note that responsiveness may be influenced by periods of high API use, or by your internet speed and connectivity.
Caching
The API requests are cached, and the cache is updated daily and whenever new data is published.
Paging
Currently there is no pagination built into the API.
Rate limiting
Currently there is no imposed rate limiting, however API usage will be monitored and limiting may be imposed if issues arise.
Contact
Please use the details on the contact page to request further information or assistance.
License
Material that can be copied or downloaded from this website has been released under a Creative Commons BY 3.9 (CC-BY 3.0) license. Further information can be found on the Copyright page.
Transitioning from the old MyHospitals API
The old MyHospitals API had 3 primary resources:
- /api/hospitals – a list of public hospitals within MyHospitals
- /api/indicators – a list of all indicators measured in the MyHospitals website
- /api/datasets – a custom dataset for a requested set of indicators
These legacy endpoints are still available on the new API and can be found in version 0 of the API.
The legacy endpoints are now:
- https://myhospitalsapi.aihw.gov.au/api/v0/retired-myhospitals-api/datasets
- https://myhospitalsapi.aihw.gov.au/api/v0/retired-myhospitals-api/hospitals
- https://myhospitalsapi.aihw.gov.au/api/v0/retired-myhospitals-api/indicators
Where possible, API users are encouraged to migrate their applications to use the new API. Details on the new calls can be found in the OpenAPI definition.
API schemas
The MyHospitals API will be self-explanatory to experienced developers, except for the terminology and data schema it uses. To accelerate your understanding of the API and its data, consult the API schemas for details about the data and descriptions of common terms.
MyHospitals API Schemas (PDF 547kB)
Examples
These examples show the different ways you can access MyHospitals data using the API.
About measures
One way to access MyHospitals data is by using a measure. The MyHospitals API organises data into a measure hierarchy:
- MeasureCategory – A grouping of measures. For example: MyHospitals ED Waiting Times
- Measure – A statistic used to measure something. For example: Percentage of patients who commenced treatment within the recommended time
- ReportedMeasure – A disaggregated measure. For example: Percentage of patients who commenced treatment within the recommended time (urgent presentations only)
- Measure – A statistic used to measure something. For example: Percentage of patients who commenced treatment within the recommended time
You can use API calls to drill down into this hierarchy and request the data you are interested in.
Return data
Requesting data by measure will return all the available data for that measure. For example, an API request could return data at the hospital, local hospital network (LHN), state and territory, PHN, hospital peer group, and national level depending on what data is available.
Example 1.1 – Getting data by Measure
Follow these steps to get data using a measure:
- Access the API’s interactive homepage Go to https://myhospitalsapi.aihw.gov.au/index.html.
- Choose a MeasureCategory On the interactive page, go to MeasureCategories and try out the /api/v1/measure-categories API call - https://myhospitalsapi.aihw.gov.au/api/v1/measure-categories . The response includes the names and codes of all available measure categories. Select one of the measure categories for step 3.
- Choose a Measure Go to Measures and try out the /api/v1/measure-categories/{measure-category-code}/measures API call, using a measure category code chosen from step 2 - for example, "MYH-ED-WAITS" https://myhospitalsapi.aihw.gov.au/api/v1/measure-categories/myh-ed-waits/measures. The response will contain a list of all available measures in the chosen category. Alternatively, you can explore all measures in all categories - https://myhospitalsapi.aihw.gov.au/api/v1/measures. Select one of the measures for step 4.
- Get all the data items for a Measure Try out the /api/v1/measures/{measure-code}/data-items API call, using a measure code chosen from step 3. For example, "MYH0010" returns all the available data items for the measure "Percentage of patients who commenced treatment within the recommended time" - https://myhospitalsapi.aihw.gov.au/api/v1/measures/MYH0010/data-items. Once you have acquired the data items you want, you can use them in your systems or applications.
Example 1.2 – Getting data by Reported Measure
Follow these steps to get data using a reported measure (a measure with disaggregations):
- Access the API’s interactive homepage Go to https://myhospitalsapi.aihw.gov.au/index.html.
- Choose a ReportedMeasure On the API’s interactive homepage, go to ReportedMeasures and try out the /api/v1/reported-measures API call - https://myhospitalsapi.aihw.gov.au/api/v1/reported-measures. Optionally, provide a measure_code as a parameter to filter to the ReportedMeasures for that specific measure. For example, using the measure code "MYH0010" the response only returns the reported measures for the measure "Percentage of patients who commenced treatment within the recommended time" - https://myhospitalsapi.aihw.gov.au/api/v1/reported-measures?measure_code=MYH0010
- Get all the data for a ReportedMeasure Try out the /api/v1/reported-measures/{reported-measure-code}/data-items API call, using a reported measure code selected in step 2. For example, "MYH-RM0037" returns data items for the measure "Percentage of patients who commenced treatment within the recommended time", but only for Urgent presentations - https://myhospitalsapi.aihw.gov.au/api/v1/reported-measures/MYH-RM0037/data-items. Once you have acquired the data items you want, you can use them in your systems or applications.
About reporting units
A reporting unit indicates what unit of analysis a specific data value corresponds to. This could be a specific hospital, or a geographical area like a state or territory.
Return data
Requesting data by reporting unit will return all the available data for that reporting unit across all available measures.
Example 2 – Getting data by ReportingUnit
Follow these steps to get data using a reporting unit:
- Access the API’s interactive homepage Go to https://myhospitalsapi.aihw.gov.au/index.html.
- Choose a ReportingUnit On the interactive page, go to ReportingUnits and try out the /api/v1/reporting-units API call - https://myhospitalsapi.aihw.gov.au/api/v1/reporting-units. The response includes the names and codes of all available reporting units. Select one of the reporting units for step 3.
- Get all the data items for a ReportingUnit Try out the /api/v1/reporting-units/{reporting-unit-code}/data-items API call, using a reporting unit code chosen from step 3. For example, "H0021" returns all the available data items for the hospital "Royal Prince Alfred Hospital" - https://myhospitalsapi.aihw.gov.au/api/v1/reporting-units/H0021/data-items. Once you have acquired the data items you want, you can use them in your systems or applications.
About datasets
A data set represents a specific data period for a specific reported measure and is used to group comparable data values. A data period may cover a financial year, like for emergency department waiting times or it may cover a specific Audit period, like for hand hygiene rates.
Return data
Requesting data by data set will return all the available data for a specific data period and a specific reported measure across all reporting units.
Example 3 – Getting data by DataSet
Follow these steps to get data using a data set:
- Access the API’s interactive homepage Go to https://myhospitalsapi.aihw.gov.au/index.html.
- Choose a DataSet On the interactive page, go to DataSets and try out the /api/v1/datasets API call - https://myhospitalsapi.aihw.gov.au/api/v1/datasets. The response includes the names and ids of all available datasets . Select one of the datasets for step 3.
- Get all the data items for a DataSet Try out the /api/v1/datasets/{dataset-id}/data-items API call, using a dataset id chosen from step 3. For example, dataset id 41 returns all the available data items for the data period 2012-13 and the reported measure "Resuscitation" of the measure "Number of patients presenting to the emergency department" - https://myhospitalsapi.aihw.gov.au/api/v1/datasets/41/data-items. Once you have acquired the data items you want, you can use them in your systems or applications.
About flat data extracts
You can use the flat data extract API calls to get MyHospitals data in a flattened structure, meaning that each item of data is provided in a simple way where the data values and related information are easily accessible.
Return data
Requesting data in a flat data extract returns up to 1000 data items at a time from a specific measure category. A flat data extract retrieves data in a flattened structure with each item corresponding to a single data point and can be optionally filtered.
Example 4 – Getting data in a flat data extract
- Access the API’s interactive homepage Go to https://myhospitalsapi.aihw.gov.au/index.html
- Choose a MeasureCategory On the interactive page, go to MeasureCategories and try out the /api/v1/measure-categories API call - https://myhospitalsapi.aihw.gov.au/api/v1/measure-categories. The response includes the names and codes of all available measure categories. Select one of the measure categories for step 3.
- Get a flat data extract for a MeasureCategory Try out one of the two flat data extract API calls:
- /api/v1/flat-formatted-data-extract/{measure-category-code} – formatted value is provided as a string
- /api/v1/flat-data-extract/{measure-category-code} – value is provided as a number
Specify the data you want to extract using the measure category code selected in step 2 – for example, “MYH-ES” returns data items for MyHospitals elective surgery. Because these API calls only extract up to 1000 data items at a time, you also need to provide a value for the parameters skip (the number of records to skip) and top (the number of records to take). In this example you will get the first 1000 data items by using 0 for skip and 1000 for top - https://myhospitalsapi.aihw.gov.au/api/v1/flat-data-extract/MYH-ES?skip=0&top=1000 To acquire all available data using flat data extract API calls, you will need to make multiple requests for 1000 data items at a time. Consider using the optional filters available on the interactive homepage to specify the data you want. Once you have acquired the data items you want, you can use them in your systems or applications.