Applicable to: Integration Providers
Application(s): External API Software
This article will cover the following:
- Understanding API basics
- Differences between PlayHQ's Public and Private APIs
- Setting up and accessing PlayHQ Public APIs
- Troubleshooting common API issues
Related articles:
Resources:
- PlayHQ API Documentation: docs.playhq.com/tech
Understanding API Basics
If you’re an advanced API 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.
An API is a software intermediary that allows two applications to communicate with each other.
Using PlayHQ's APIs, you could:
- Display fixtures and results on your website
- Gather game statistics to publish weekend results
- Integrate PlayHQ data with other systems
What is the difference between PlayHQ Public and Private API’s?
The main difference between the private and public APIs is the selection of data returned in the response.
Public APIs 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) within the API's.
Use cases:
- Website widgets displaying fixtures, results, and ladders
- Public-facing applications accessible to all internet users
Data limitations:
- Hidden organisations, teams, or participants will not appear in results
- Respects all privacy settings configured in PlayHQ
Private APIs 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, gender etc. within the API's.
Private APIs are not to be consumed by the general public and only approved PlayHQ partners will have access.
Use cases:
- Official PlayHQ partners (e.g. referee management systems, live streaming providers)
Access requirements:
- Formal agreement with PlayHQ, including guidelines for data usage
- Authentication tokens provided by PlayHQ
Restricted access
Private APIs are those which include Authorization required (for a Bearer {JWT_Auth_Token}). These Private APIs are restricted and only accessible to approved PlayHQ partners.
Setting Up PlayHQ Public APIs
Obtaining API credentials
If you are involved with a club or league, please reach out to your association so that they can request credentials on your behalf to PlayHQ.
If you don't belong to a club but are looking to publish PlayHQ data, please submit a request through your relevant sport via https://www.playhq.com/au/contact
Finding API endpoints
- Visit the PlayHQ API Documentation at docs.playhq.com/tech
- Navigate to the relevant API endpoint in the left column, labelled "GET"
- Select the specific API you need
- Copy the API server URL (e.g. https://api.playhq.com/v1/organisations/:id/seasons)
- Drop-down the Responses titles to see all fields and their available responses that may be returned
Finding the Public APIs
Public APIs are freely available and do not require any Authorization token. If you encounter a request for an Authorization token, you've attempted to reach a Private API endpoint. These Private APIs are restricted and only accessible to approved PlayHQ partners.
Making a request with your API credentials
- Open your external API testing software (for example, Postman)
- Create a new GET request
- Paste the PlayHQ API server URL (e.g. https://api.playhq.com/v1/organisations/:id/seasons)
- Add your header parameters:
x-api-key: [also referred to as the Client ID - this is a UUID]
x-phq-tenant: [also referred to as the short-name of the sport/tenant, in lowercase - e.g. bv, afl, ca] - Add your path parameters:
where applicable - for example, id: [relevant string listed in documentation] - Send the request to validate the data returned
Frequently Asked Questions
PlayHQ offer a vast amount of data relating to competition fixtures, results and ladder within the available public APIs.
For a detailed list, look for endpoints labelled with "GET" in the PlayHQ API documentation.
Private APIs are those which include Authorization required (for a Bearer {JWT_Auth_Token}), and only approved PlayHQ partners will have access.
Organisation IDs are 32-digit unique identifiers (UUID) not readily visible on the website. To obtain one:
- Contact your league or club administrator
- Once you have the Organisation ID, you can use it to call various APIs:
-
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.
-
The base PlayHQ API Server URL in Production is: https://api.playhq.com
If you have been granted access to our UAT environment, the PlayHQ API Server URL in UAT is: https://api.uat.playhq.com
Complete endpoint information for each API can be found in the PlayHQ API documentation.
If you're finding incomplete or missing data in your API responses, you're likely encountering pagination. For endpoints that may return large datasets, PlayHQ API implements cursor-based pagination (typically 100 items) to maintain performance. To retrieve the complete dataset, you'll need to make multiple requests.
Where metadata.hasMore is true in your API response, then there are more responses available for your request, which can be accessed with a cursor parameter. This should allow you to paginate through all available results by continuing to make requests with the latest cursor value until you receive a response where the metadata: hasMore is false.
To retrieve all available data:
- Make your initial API request to the endpoint
- Check if
metadata.hasMoreistruein the response - If yes, make another request to the same endpoint, adding the cursor parameter (i.e. ?cursor=) with the
metadata.nextCursorvalue after = from the previous response - Continue this process, collecting all results, until you receive a response where
metadata.hasMoreisfalse
Example:
// First request
GET https://api.playhq.com/v1/{endpoint}
// Response includes metadata.hasMore: true and metadata.nextCursor value
// Make subsequent request with cursor
GET https://api.playhq.com/v1/{endpoint}?cursor={cursor_value}
Always check for the metadata fields in your responses to ensure you're retrieving complete datasets.