Foireann Open Data API - Competition Endpoint

Overview

The article below outlines how to use the Competition API and includes the filters which can be used as well as some example responses. 

---

Table of Contents

• Using the Competition API
• Pagination and Sorting
• Error Handling
• Competition Filters
• Competition Sorting
• Competition Example Response

---

Using the API

Making a Request

To make a request, append the endpoint to the base URL and include the necessary parameters. All parameters are optional, however, your API key will be restricted to the Units you requested when getting your API key.

You can use any HTTP client to make requests to the API. Here’s an example with curl:

curl --location "https://api.foireann.ie/open-data/v1/competitions" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $FOIREANN_API_KEY"

To fetch all Competitions available to your API key:

GET /v1/competitions

To fetch all Senior Football Competitions for a specific County:

GET /v1/competitions?owner.id=6e5025cc-c7d6-38ae-4e72-4da893842163&grade=senior&activity=football 

---

Pagination and Sorting

All endpoints pagination and sorting. Use the page and size parameters for pagination, and the sort parameter for sorting. Multiple sort parameters are supported, but only certain fields can be used for sorting. Please find the list of supported fields in the Specification section.

The format for the sort parameter is propertyName[,(asc|desc)]*. The direction suffix is optional and the default direction is ascending. For example, to sort Fixtures by start date in descending order:

GET /v1/competitions?sort=startDate%2Cdesc&page=0&size=20

---

Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of an API request. For example, 200 OK for successful requests and 401 Unauthorized for unauthorized requests.

---

Competition Filters

GET /v1/competitions

This table provides a comprehensive overview of the filter options available for querying the competitions in the Foireann Open Data API, including the type of each filter, whether it’s a query parameter, its description, default values, and the available values where applicable.

Filters

Name	Type	Description	Default Value	Available Values
id	array[uuid]	Unique identifier of the Competition
additionalType	array[string]	Type of the Competition		club, inter_county, province, third_level, school, interfirm
activity	array[string]	Activity of the Competition		football, hurling, ladies_football, camogie, handball, rounders
grade	array[string]	Grade of the Competition		senior, intermediate, junior, u21, minor, juvenile, underage
ageLevel	array[string]	Age level of the competition
season	array[integer]	Integer year of the Competition
format	array[string]	Format of the Competition		league, cup, league_knockout
status	array[string]	Status of the Competition		active, archived
owner.id	array[uuid]	Unique identifier of the Organization who controls the Competition
isMasterCompetition	boolean	Whether the competition is part of a Master Competition
masterCompetition.id	array[uuid]	Unique identifier of the Master Competition (Long running competitions)
division.id	array[uuid]	Unique identifier of the Division of the Competition
team.id	array[uuid]	Unique identifier of a Team participating in a Competition
search	string	Free text search for a Competition by Competition/Division/Owner/Team name
page	integer	Zero-based page index (0..N)	0
size	integer	The size of the page to be returned	20
sort	array[string]	Sorting criteria in the format: property,(asc|desc)

 

---

Sorting

Field	Description
season	Sort by the season of the competition (e.g., 2023, 2024, etc.)
createDate	Sort by the date and time the competition was created
updateDate	Sort by the date and time the competition was last updated

---

Example response

{
   "data": [
      {
         "id": "08ea1210-0aba-4f93-96ad-eecdf5f5af21",
         "name": "GAA Football All-Ireland Senior Championship",
         "legalName": "GAA Football All-Ireland Senior Championship",
         "sponsor": "",
         "sponsorPosition": null,
         "owner": {
            "id": "c4ca4238-a0b9-2382-0dcc-509a6f758491",
            "name": "GAA"
         },
         "masterCompetition": {
            "id": "c5b8b79e-6072-47a1-b813-9f5e8364bc1a",
            "name": "GAA Football All-Ireland Senior Championship"
         },
         "additionalType": "inter_county",
         "grade": "senior",
         "format": "league_knockout",
         "activity": "football",
         "ageLevel": "Senior",
         "season": "2023",
         "status": "active",
         "createDate": "2022-11-02T10:22:39Z",
         "updateDate": "2022-12-21T09:26:16Z",
         "divisions": [],
         "links": {
            "self": {
               "href": "https://api.foireann.ie/open-data/v1/competitions?id=08ea1210-0aba-4f93-96ad-eecdf5f5af21"
            }
         }
      }
   ],
   "links": {
      "self": {
         "href": "https://api.foireann.ie/open-data/v1/competitions?id=08ea1210-0aba-4f93-96ad-eecdf5f5af21&page=0&size=20"
      }
   },
   "page": {
      "page": 0,
      "size": 20,
      "totalPages": 1,
      "totalElements": 1
   }
}