The below support article will give a brief overview of what an API is, the difference between PlayHQ’s public and private API’s, how to set up the PlayHQ API as well as some frequently asked questions.
What is an API?
If you’re an advanced user, you can probably skim past this section, but if you’ve stumbled across this page curious about what an API is, the below might give you some context.
Intermediate User: API is the acronym for Application Programming Interface, which is a software intermediary that allows two applications to talk to each other.
Beginner User: Remember the humble fax machine? Popular in the 80's and 90's, fax machines were used to scan original documents which were transmitted through a telephone system.
So back in the 1980's, if you wanted to send someone the league results to display in their office or home, a fax machine was used to scan the league results document, enter in the recipient's fax number and then transmitted to its destination. The receiving fax machine would then print the results to be displayed in the office. Quite an invention for the 1980's.
In our days, the use of API's to display information on websites could be likened to a fax machine. An API is the calling code that works as the transmitter to display information on participating websites.
What is the difference between PlayHQ Public and Private API’s?
The main difference between PlayHQ’s public and private API's is the visibility of data and who it’s consumed by. An agreement with PlayHQ is required to be set up for the use of Private API's.
Public
The API will honour the visibility settings on PlayHQ by only sending related data that is set to VISIBLE within PlayHQ’s admin portal.
For example, if an administrator sets an organisation to HIDDEN on PlayHQ’s admin portal, we will not send that organisation or any subsidiary information (competitions, fixtures underneath) via the API's.
Public API's are predominantly used as widgets on websites that display fixtures, results and ladders, these API’s can be accessed by all internet users.
Private
The API will send data regardless of whether it has been set to VISIBLE or HIDDEN within the PlayHQ portal.
For example, if a participant has set their profile set to HIDDEN on PlayHQ’s participant portal, we will pass their name, email and gender within the API's.
Private API's are only to be used by PlayHQ’s official partners through an integration arrangement. There are clear contracts and guidelines in place for use of this data.
What credentials do I need for a Public API?
The Public APIs require the below header parameters to get a successful response. These are the credentials that have been provided by the PlayHQ team.
x-api-key (also referred to as the Client ID)
x-phq-tenant (usually refers to the sport/association)
We will demonstrate how to obtain these header parameters a little further down the support article.
What is the Private API used for?
Private API's are exclusively for PlayHQ platform partners. These integrations are set up through consultation and contract arrangements.
An authentication token is only required for the API’s classified as Private. These are not to be consumed by the general public and only approved PlayHQ partners will have access.
Introducing the PlayHQ API Documentation
Welcome to our API documentation – docs.playhq.com/tech
On the left column is the list of our API's.
Click the drop down to the relevant section then the specific API you're wanting.
On the right hand side, you will see response sample that accompanies the PlayHQ API server drop down (eg. https://api.playhq.com/v1/organisations/:id/seasons)
Copy this API server URL to then transfer into API software, we will get into this a little further down in the support article.
Take note of the required Header Parameters which are needed to successfully create the API.
The x-api-key (Client ID) can be obtained from the Public API self-serve feature. The below video demonstrates how to use the self-serve feature within the PlayHQ administrator portal.
The x-phq-tenant is the tenant ID (eg. bv, afl, na).
Note: For private API’s only you’ll need to generate an authentication token. This can be done in consultations with PlayHQ.
Using API Software
To validate the API, you'll need to use an external API platform for building and using API’s. For this example, we will be using a software called Postman (https://www.postman.com/)
Paste the PlayHQ API Server url that you’ve copied from docs.playhq.com/tech
Amend the header parameters as mentioned previously which include the x-api-key (client ID) and x-phq-tenant (tenant ID). If you're unsure how to obtain these credentials, scroll above for further details.
Validating the data that the API can return
Now that you’ve updated the PlayHQ API Server URL within Postman (or other API software), you can validate the data that the API can return. For example, if you’re wanting to return fixture data, this is where you can ensure that the data will successfully carry through.
An example of using the API within WIX
A common use of our Public API is public facing widgets on websites. The below video showcases how the PlayHQ Public API integrates with popular content management systems and websites such as Wix.
FAQ's
What data can be retrieved from the PlayHQ APIs?
PlayHQ offers a vast amount of data within the available APIs. This includes data related to an organisation's season, grade, competition, fixtures, ladders, competition registrations and game results.
For a more detailed view on what is available click here PlayHQ External API
Note: API’s are labeled with GET.
The API’s require a Organisation ID to be passed, where do I get this?
As a starting point you will need to have a Organisation ID. This ID is unique, made up of 32 digits, and is not readily available on the website. Please contact your league or club administrator for this information.
Once you have your Organisation ID, you will be able to call multiple API's to get the necessary ID.
The following is a guide to retrieve certain PlayHQ ID’s. There are other API's that can be used to get this information.
Using the Organisation ID, call "Seasons for organisation" to retrieve season ID's.
Using a season ID, Call "Grades for season" to retrieve grade ID's.
Using a grade ID, call “fixture for grade” to retrieve game ids
Using a game ID, call “Summary for game (Public)” to get results for a game
What is the URL for the PlayHQ API server?
PlayHQ API Server: https://api.playhq.com/
Endpoint information for each API can be found on the PlayHQ API documentation site: PlayHQ External API
For example: Fixture for team API call would look like the below (with :id replaced with team id)
