user:
userid:
representing:

On this page:

 

Lodging an application via the HPP

Log into the HPP and navigate to the Application tab from the Services page. For information on how to access the HPP, please view our article on Accessing the HPP.

 

Complete a Request access to PBS embargo data API by selecting the 'New application' > 'Medicinal Products and vaccines' > 'Request access to PBS embargo data API' menu option. Follow the prompts within the application to lodge the request.

 

Once your application has been approved, you will receive correspondence with the category Embargo API access details which can be accessed via the HPP. Your correspondence will include: 

  1. Client ID

  2. Client secret

  3. Tenant ID

  4. Scope

  5. Developer Portal URL

An example of the correspondence is shown in Figure 1.

Figure 1: Screenshot of the Embargo API access details correspondence 
 

Accessing the Developer Portal

Using the Developer Portal link provided within the Embargo API access details correspondence received in the HPP, log into your Developer Portal account. When logging in, please ensure that you select the following options in the order indicated below. You must use the same digital identity that you used to access the HPP.

  1. Login with myGovID (Figure 2)
  2. Digital Identity and RAM (Figure 3)
  3. Select myGovID (Figure 4)

Figure 2. Screenshot of Developer Portal sign in options with 'Login with mygovID' highlighted

 

Figure 3: Screenshot of Health Authentication Gateway with Digital Identity and RAM selection highlighted 

Figure 4: Screenshot of Digital Identity page showing 'Select myGovID' option

 

Generating a subscription key

Once you have logged into the Developer Portal, navigate to the Profile tab and generate a subscription key by clicking show on the primary key in your User profile. Details on how to retrieve the subscription key are shown in Figure 5. 

Figure 5: Screenshot of the Developer Portal 'Profile' page 

 

Viewing API endpoints

To view all the API endpoints, including versions, select the ‘View APIs’ option within the Developer Portal, then select the hyperlink to the PBS API EMBARGO. 

From this page you can: 

  1. Set the version 

  1. Select the relevant table 

  1. Retrieve the API endpoint 

Figure 6 shows the API page in the Developer Portal, with guidance on actions that can be performed on this page.  

Figure 6: Screenshot of the Developer Portal 'API' page 

 

Obtaining an Access token through postman

Using the Tenant ID provided in the Embargo API access details correspondence (Item 3 in Figure 1), create the URL from which you will obtain the Bearer Token as follows:

https://login.microsoftonline.com/[TenantID]/oauth2/v2.0/token

Once you have your URL, open Postman and follow the steps below to obtain your access token: 

  1. Within Postman, open a new tab by clicking '+' at the top of the window shown in Figure 7. 

Figure 5: Screenshot of the ‘+’ button 

This will bring up a blank request as shown in Figure 6. 

Figure 7: Screenshot of a blank request with ‘Enter request URL’ highlighted 

  1. Within this page, paste your URL into the 'Enter request URL' field as shown in Figure 7.  

  1. Navigate to the 'Body' tab and select the radio button for ‘form-data’ as shown in Figure 8. This will display the KEY and VALUE columns. 

Figure 8: Screenshot of Body tab with ‘form-data’ radio button highlighted 

  1. In the KEY column, type in 'client_id', 'client_secret', 'scope' and 'grant_type' as shown in Figure 9. 

Figure 9: Screenshot of Body tab with KEY column highlighted

  1. In the corresponding rows within the VALUE column, enter your Client ID, Client secret and Scope from your correspondence (shown as items 1, 2 and 4 in Figure 1) into the VALUE column as shown in Figure 9.
  2. Manually enter 'client_credentials' into the VALUE column for 'grant_type' as shown in Figure 10.

Figure 10: Screenshot of Postman with credentials entered

  1. Once input, hit 'Send'. This will generate the Access token as shown in Figure 10.
  2. Select and copy this as indicated in Figure 9. Please note that your access token will only last an hour once it has been generated.

 

Using an access token to access the API

Open a new tab in Postman once more (Figure 5) and enter the request URL for the API. This can be obtained from the Developer Portal in the API tab. Refer to item 3 as shown in Figure 4 to locate the URL. Please note that you should exclude everything from ‘[‘ to ‘]’ at the end of the URL.

Within the Authorization tab, ensure the Type is set to Bearer Token and paste the access token copied from the Postman ‘Post’ page, as described in step Obtaining an Access token through Postman. The location of fields that need to be populated is shown in Figure 11.

Figure 11: Screenshot of Postman 'Get' page and where to input the API URL, Bearer Token and Access Token

Navigate to the Header tab and manually type ‘subscription-key’ into the KEY column and in the VALUE column insert the subscription key (primary or secondary) retrieved from the Developer Portal in step Generating a subscription key (see Figure 3 for further details). Figure 12 provides guidance on the field that needs to be populated with the subscription key.

Figure 12: Screenshot of Postman 'Get' page and where to input the subscription key

Once completed, select send. This will return the PBS Embargo data from the requested endpoint.

 

Frequently asked questions

In this section:  

What is the approach in the model for schedules and SoC?

The PBS APIs have been built in concert with a Physical Data Model that represents a de-normalised view of the PBS to assist with easier consumption of the data. Each endpoint represents one of the tables displayed on the data model.

A complete set of data is pushed into the API system when a new monthly Schedule is released. The Schedule API contains the records associated with all available data in the API system. The Schedule number appears on every endpoint and is used to link all relevant data records together.

The Summary of Changes endpoint contains the records relating to the events for specific pieces of data (i.e. endpoint/field) relating to any changes that have occurred between the current and previous schedules. For instance, if an Item’s Claimed_Price has been updated then a record will appear in the current Schedule’s data that shows the change and includes the actual SQL statement that can be applied to the previous Schedule’s data to create the current version of that field.

By applying all changes held in the Summary of Changes endpoint for the current schedule against the data from the previous schedule, a User can recreate the current schedule’s data.

The SQL statements contained in the Summary of Changes are produced in SQL Server syntax and can be applied to the data using the following process:

  • Data for the previous Schedule is loaded into a database. (Can be achieved by downloading all endpoint data for the previous Schedule and uploading into an empty database)
  • All values of the Schedule_Code are updated to reflect the current Schedule_Code.
  • The SQL statements for the current Schedule can then be applied. (Though care must be taken to apply changes in the most logical sequence to ensure primary key/foreign key constraints are maintained.)
 

How does the design handles intra-release changes?

The cadence of release will follow the current XML data file release process, that is new files will be released on a monthly basis.

Where the need arises for an additional release of data, a new Schedule number will be created, and the API data will be refreshed with all relevant data for that Schedule, in much the same way as a normal release occurs currently.

The Summary of Changes endpoint will reflect the data changes between Schedules in the same way.

 

How are API versions / deprecations being supported?

Like any system, changes may be required to introduce new improvements or remedy a previous error. To ensure that users are not inconvenienced by sudden changes to the API endpoints, previous (or deprecated) versions of the API endpoints will still be available for a period following a new release of updated endpoints.

Access to the current and previous versions of the API endpoints will be controlled through changes to the of URLs of the endpoints themselves.

As an example, Version 1 of an endpoint may have the URL:

https://data-api.health.gov.au/pbs-embargo/api/VERSION1/<endpoint>

whereas Version 2 of that endpoint may be given the URL:

https://data-api.health.gov.au/pbs-embargo/api/VERSION2/<endpoint>

The URL names allocated to endpoints are specifically referenced on the relevant Swagger documentation page under the “Request” heading.

 

Can the API be downloaded as a JSON or CSV?

The PBS DDS API endpoints have been developed to enable data to be received in either JSON (JavaScript Object Notation) or CSV (Comma Separated Values) format.

This is achieved by using the “Accept” parameter in the API Get statement header. For JSON use Accept = “application/json” (this is the default); for CSV use Accept = “text/csv”.

In Postman, this is achieved by setting an “Accept” key in the Headers tab. Once the data has been received, the file can be downloaded and saved.

 

How can the API be filtered by PBS code and program?

The API endpoints have been created with ease of use in mind, and the amount of data that can be requested can be refined using a series of parameters specific to each endpoint.

These are documented on the Swagger page for each endpoint under the “Request Parameters” header.

Filtering of the data can be achieved by adjusting the “Get” statement to include the relevant parameter.

e.g. for the Items endpoint, requesting a specific Schedule would look similar to this:

https://data-api.health.gov.au/pbs-embargo/api/VERSION2/items?schedule_code=1234

Using a tool, such as Postman, this can be achieved by adding an entry to the Query Params list. The tool will then automatically add the parameter to the Get statement executed.

 

Can the API be implemented into Users systems?

To make the transition of receiving systems as simple as possible, the PBS DDS API system has been designed to effectively emulate the existing XML file download system as closely as possible.

The intended operation is for end Users to access the API endpoints and retrieve all data associated with a Schedule in one request and download that file to local storage ready for upload into their own systems/databases.

To ensure a higher level of stability of the API system, a limit of one request per second has been implemented. The system has not been designed as a high-volume real-time system, but rather as a data storage and retrieval system to enable software vendors and users the ability to download and store local copies of the data.

How are Restrictions stored in the API data?

A resource is available to assist with piecing together restriction fragments. Please note the attachments are subject to updates, the latest copy is available via the link in the Attachments section below. 

 

API data model and data dictionary

The following attachments are subject to updates, the latest copy is available via the following links.

Attachments: