Metadata API Guide

Overview

The Metadata API provides reference data for sports, locations, leagues, periods, and incidents. Use these endpoints to look up IDs and names for filtering and display purposes.

Base URL: https://engage-api.lsports.eu/api/metadata

All endpoints use the same credential-based authentication as the Customers API. Omit optional filter fields (or pass an empty array) to return the full dataset.

---

Common request fields

Field	Type	Required	Description
packageId	integer	Yes	Your package ID
username	string	Yes	Your username
password	string	Yes	Your password

Common validation errors (400)

• "PackageId must be a positive integer"
• "Username is required"
• "Password is required"
• "Invalid package credentials"
• "Package is inactive"

Server error (500)

{ "success": false, "message": "Unexpected error. Please contact [e-mail]" }

---

Endpoints

1. Get Sports

Returns a dictionary of sport IDs and names available in the platform.

POST https://engage-api.lsports.eu/api/metadata/sports

Request body

{
  "packageId": 123,
  "username": "[e-mail]",
  "password": "password123",
  "sportIds": [1, 2]
}

Field	Type	Required	Description
sportIds	integer[]	No	Filter by specific sport IDs. Returns all sports if omitted or empty.

Success (200)

{
  "success": true,
  "data": {
    "1": "Soccer",
    "2": "Basketball",
    "3": "Tennis"
  }
}

cURL

curl -X POST https://engage-api.lsports.eu/api/metadata/sports \
  -H "Content-Type: application/json" \
  -d '{"packageId": 123, "username": "[e-mail]", "password": "password123"}'

---

2. Get Locations

Returns a dictionary of location IDs and names (countries and regions).

POST https://engage-api.lsports.eu/api/metadata/locations

Request body

{
  "packageId": 123,
  "username": "[e-mail]",
  "password": "password123",
  "locationIds": [1, 2]
}

Field	Type	Required	Description
locationIds	integer[]	No	Filter by specific location IDs. Returns all locations if omitted or empty.

Success (200)

{
  "success": true,
  "data": {
    "1": "England",
    "2": "Spain",
    "3": "Germany"
  }
}

cURL

curl -X POST https://engage-api.lsports.eu/api/metadata/locations \
  -H "Content-Type: application/json" \
  -d '{"packageId": 123, "username": "[e-mail]", "password": "password123"}'

---

3. Get Leagues

Returns a dictionary of league IDs and names. Leagues can be filtered by sport and/or location.

POST https://engage-api.lsports.eu/api/metadata/leagues

Request body

{
  "packageId": 123,
  "username": "[e-mail]",
  "password": "password123",
  "sportIds": [1],
  "locationIds": [1]
}

Field	Type	Required	Description
sportIds	integer[]	No	Filter by sport IDs.
locationIds	integer[]	No	Filter by location IDs.

Success (200)

{
  "success": true,
  "data": {
    "8": "Premier League",
    "9": "Championship",
    "10": "League One"
  }
}

cURL

curl -X POST https://engage-api.lsports.eu/api/metadata/leagues \
  -H "Content-Type: application/json" \
  -d '{"packageId": 123, "username": "[e-mail]", "password": "password123", "sportIds": [1], "locationIds": [1]}'

---

4. Get Periods

Returns periods grouped by sport. Each period has a display ID and a name.

POST https://engage-api.lsports.eu/api/metadata/periods

Request body

{
  "packageId": 123,
  "username": "[e-mail]",
  "password": "password123",
  "sportIds": [1, 2]
}

Field	Type	Required	Description
sportIds	integer[]	No	Filter by sport IDs. Returns periods for all sports if omitted or empty.

Success (200)

{
  "success": true,
  "data": {
    "1": [
      { "id": 1, "name": "1st Half" },
      { "id": 2, "name": "2nd Half" },
      { "id": 3, "name": "Extra Time 1st Half" },
      { "id": 4, "name": "Extra Time 2nd Half" }
    ],
    "2": [
      { "id": 1, "name": "1st Quarter" },
      { "id": 2, "name": "2nd Quarter" },
      { "id": 3, "name": "3rd Quarter" },
      { "id": 4, "name": "4th Quarter" }
    ]
  }
}

The top-level keys are sport IDs. The id field within each period is the display ID used in fixture and incident messages — use this to match periods in your integration.

cURL

curl -X POST https://engage-api.lsports.eu/api/metadata/periods \
  -H "Content-Type: application/json" \
  -d '{"packageId": 123, "username": "[e-mail]", "password": "password123"}'

---

5. Get Incidents

Returns a flat dictionary of all incident type IDs and names. No filters are supported — the full list is always returned.

POST https://engage-api.lsports.eu/api/metadata/incidents

Request body

{
  "packageId": 123,
  "username": "[e-mail]",
  "password": "password123"
}

Success (200)

{
  "success": true,
  "data": {
    "1": "Goal",
    "2": "Yellow Card",
    "3": "Red Card",
    "4": "Substitution"
  }
}

cURL

curl -X POST https://engage-api.lsports.eu/api/metadata/incidents \
  -H "Content-Type: application/json" \
  -d '{"packageId": 123, "username": "[e-mail]", "password": "password123"}'