How To Use PlayHQ API's

Applicable to: Integration Providers
Application(s): External API Software

This article will cover the following:

  1. Understanding API basics
  2. Differences between PlayHQ's Public and Private APIs
  3. Setting up and accessing PlayHQ Public APIs
  4. Troubleshooting common API issues

Related articles:

Resources:

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 Private APIs

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


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

  1. Visit the PlayHQ API Documentation at docs.playhq.com/tech
  2. Navigate to the relevant API endpoint in the left column, labelled "GET"
  3. Select the specific API you need
  4. Copy the API server URL (e.g. https://api.playhq.com/v1/organisations/:id/seasons)
  5. 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

  1. Open your external API testing software (for example, Postman)
  2. Create a new GET request
  3. Paste the PlayHQ API server URL (e.g. https://api.playhq.com/v1/organisations/:id/seasons)
  4. 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]
  5. Add your path parameters:
    where applicable - for example, id: [relevant string listed in documentation]
  6. Send the request to validate the data returned


Frequently Asked Questions

What data can I retrieve from PlayHQ Public APIs?

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.

How do I find the Organisation ID?

Organisation IDs are 32-digit unique identifiers (UUID) not readily visible on the website. To obtain one:

  1. Contact your league or club administrator
  2. 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.

What is the base URL for PlayHQ API calls?

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.

My request hasn't returned all available results. How can I find more?

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:

  1. Make your initial API request to the endpoint
  2. Check if metadata.hasMore is true in the response
  3. If yes, make another request to the same endpoint, adding the cursor parameter (i.e. ?cursor=) with the metadata.nextCursor value after = from the previous response
  4. Continue this process, collecting all results, until you receive a response where metadata.hasMore is false

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.

Was this article helpful?
1 out of 1 found this helpful