Skip to main content

Foireann Open Data API - Fixtures & Results Endpoint

Foireann Support
  • Updated

Overview

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

Table of Contents

Using the Fixtures & Results 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/fixtures" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $FOIREANN_API_KEY"

To fetch all Fixtures available to your API key:

GET /v1/fixtures

To fetch Fixtures available to your API key, with a start date between 2023-03-01 and 2023-03-02:

GET /v1/fixtures?startDateFrom=2024-03-01T00%3A00Z&startDateTo=2023-03-02T00%3A00Z

Please note that values for parameters must be URL encoded.

To fetch Fixtures for a specific Competition:

GET /v1/fixtures?competition.id=08ea1210-0aba-4f93-96ad-eecdf5f5af21

Where there endpoint accepts multiple values for a parameter (i.e. array[type]), simply send the parameter multiple times. For example, to fetch fixtures for both Football and Hurling:

GET /v1/fixtures?activity=football&activity=hurling

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/fixtures?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.

Fixtures & Results Filters

GET /v1/fixtures

This table provides a comprehensive overview of the filter options available for querying the fixtures 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 for the Fixture

 

 

involvedTeams

array[uuid]

Unique identifier for an Organization participating in a Fixture

 

 

isResult

boolean

Whether the Fixture is a result or not

 

 

startDateFrom

ISO datetime

The start date range of the Fixture

 

 

startDateTo

ISO datetime

The end date range of the Fixture

 

 

startDateDaysBefore

string

The number of days before the start date of the Fixture

 

 

startDateDaysAfter

string

The number of days after the start date of the Fixture

 

 

showTbc

boolean

Whether to include Fixtures where a Team has not been assigned yet

 

 

showByeGames

boolean

Whether to include Fixtures where a Team has a bye

 

 

owner.id

array[uuid]

The Unique Identifier of the Owning Organization of a Fixture

 

 

owner.ancestors

array[uuid]

The Unique Identifier of the Ancestor of the Organization that owns the Fixture

 

 

competition.id

array[uuid]

The Unique Identifier of the Competition of the Fixture

 

 

competition.additionalType

array[string]

The Type of Competition of the Fixture

 

club, inter_county, province, third_level, school, interfirm

competition.activity

array[string]

The Activity of the Competition of the Fixture

 

football, hurling, ladies_football, camogie, handball, rounders

competition.grade

array[string]

The Grade of the Competition of the Fixture

 

senior, intermediate, junior, u21, minor, juvenile, underage

competition.format

array[string]

The Format of the Competition of the Fixture

 

league, cup, league_knockout

competition.ageLevel

array[string]

The Age Level of the Competition of the Fixture

 

 

competition.season

array[string]

The Season of the Competition of the Fixture

 

 

competition.status

array[string]

The Activity of the Competition of the Fixture

 

active, archived

division.id

array[uuid]

Unique identifier of the Division of the Fixture

 

 

division.format

array[string]

The format of the Division of the Fixture

 

league, cup

place.id

array[uuid]

Unique identifier of the Place (Venue) of the fixture

 

 

search

string

Free text search for a Fixture by Competition/Division/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)

 

 

 

Fixture & Results Sorting

Field

Description

startDate

Sort by the start date and time of the fixture

createDate

Sort by the date and time the fixture was created

updateDate

Sort by the date and time the fixture was last updated

 

Fixtures & Results Example response

{
  "data": [
    {
      "id": "cb760b1f-0c97-4b44-be6e-efd9a504e5f8",
      "involvedTeams": [
        "6e5025cc-c7d6-38ae-4e72-4da893842163",
        "a381c2c3-5c91-57f6-b67f-d07d5a202155"
      ],
      "homeTeam": {
        "id": "6e5025cc-c7d6-38ae-4e72-4da893842163",
        "name": "Kerry",
        "placeholder": null,
        "goals": 0,
        "points": 17,
        "isBye": false,
        "isConceded": false
      },
      "awayTeam": {
        "id": "a381c2c3-5c91-57f6-b67f-d07d5a202155",
        "name": "Mayo",
        "placeholder": null,
        "goals": 1,
        "points": 19,
        "isBye": false,
        "isConceded": false
      },
      "startDate": "2023-05-20T14:00:00Z",
      "startDateRangeFrom": null,
      "startDateRangeTo": null,
      "isResult": true,
      "round": "Round 1",
      "refereeName": "Sean Hurson",
      "broadcastDetails": {
        "summary": "GAAGO",
        "url": null,
        "logoUrl": null
      },
      "notes": null,
      "isPostponed": false,
      "isRescheduled": false,
      "isReplay": false,
      "isAbandoned": false,
      "isNeverPlayed": false,
      "isExtraTimePlayable": false,
      "reportUrl": null,
      "status": null,
      "createDate": "2023-05-01T10:37:11Z",
      "updateDate": "2023-05-22T05:37:37Z",
      "place": {
        "id": "3eda4e6f-5c16-4271-bf8a-555243ffbfb3",
        "name": "Fitzgerald Stadium",
        "latitude": null,
        "longitude": null
      },
      "owner": {
        "id": "c4ca4238-a0b9-2382-0dcc-509a6f758491",
        "name": "GAA"
      },
      "division": {
        "id": "7c929630-38eb-447c-8d75-e8db4cf9116c",
        "name": "GAA Football All-Ireland Senior Championship Group 1",
        "abbreviatedName": "SFCA",
        "format": "league"
      },
      "competition": {
        "id": "08ea1210-0aba-4f93-96ad-eecdf5f5af21",
        "name": "GAA Football All-Ireland Senior Championship",
        "legalName": "GAA Football All-Ireland Senior Championship",
        "sponsor": "",
        "sponsorPosition": null,
        "additionalType": "inter_county",
        "format": "league_knockout",
        "activity": "football",
        "grade": "senior",
        "gender": "male",
        "ageLevel": "Senior",
        "season": "2023",
        "status": "active"
      },
      "cccRulings": null,
      "links": {
        "self": {
          "href": "https://api.foireann.ie/open-data/v1/fixtures?id=cb760b1f-0c97-4b44-be6e-efd9a504e5f8"
        },
        "competition": {
          "href": "https://api.foireann.ie/open-data/v1/competitions?id=08ea1210-0aba-4f93-96ad-eecdf5f5af21"
        }
      }
    },
    {
      /* omitted for brevity */
    }
  ],
  "links": {
    "self": {
      "href": "https://api.foireann.ie/open-data/v1/fixtures?competition.id=08ea1210-0aba-4f93-96ad-eecdf5f5af21&page=0&size=20"
    },
    "first": {
      "href": "https://api.foireann.ie/open-data/v1/fixtures?competition.id=08ea1210-0aba-4f93-96ad-eecdf5f5af21&page=0&size=20"
    },
    "next": {
      "href": "https://api.foireann.ie/open-data/v1/fixtures?competition.id=08ea1210-0aba-4f93-96ad-eecdf5f5af21&page=1&size=20"
    },
    "last": {
      "href": "https://api.foireann.ie/open-data/v1/fixtures?competition.id=08ea1210-0aba-4f93-96ad-eecdf5f5af21&page=2&size=20"
    }
  },
  "page": {
    "page": 0,
    "size": 20,
    "totalPages": 3,
    "totalElements": 44
  }
}

 

Related articles

Comments

0 comments

Article is closed for comments.