> For the complete documentation index, see [llms.txt](https://docs.lsports.eu/u/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lsports.eu/u/engage/hyper-livescore/metadata-api-guide.md).

# 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)

```json
{ "success": false, "message": "Unexpected error. Please contact support@lsports.eu" }
```

***

## 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**

```json
{
  "packageId": 123,
  "username": "user@example.com",
  "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)**

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

**cURL**

```bash
curl -X POST https://engage-api.lsports.eu/api/metadata/sports \
  -H "Content-Type: application/json" \
  -d '{"packageId": 123, "username": "user@example.com", "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**

```json
{
  "packageId": 123,
  "username": "user@example.com",
  "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)**

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

**cURL**

```bash
curl -X POST https://engage-api.lsports.eu/api/metadata/locations \
  -H "Content-Type: application/json" \
  -d '{"packageId": 123, "username": "user@example.com", "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**

```json
{
  "packageId": 123,
  "username": "user@example.com",
  "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)**

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

**cURL**

```bash
curl -X POST https://engage-api.lsports.eu/api/metadata/leagues \
  -H "Content-Type: application/json" \
  -d '{"packageId": 123, "username": "user@example.com", "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**

```json
{
  "packageId": 123,
  "username": "user@example.com",
  "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)**

```json
{
  "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**

```bash
curl -X POST https://engage-api.lsports.eu/api/metadata/periods \
  -H "Content-Type: application/json" \
  -d '{"packageId": 123, "username": "user@example.com", "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**

```json
{
  "packageId": 123,
  "username": "user@example.com",
  "password": "password123"
}
```

**Success (200)**

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

**cURL**

```bash
curl -X POST https://engage-api.lsports.eu/api/metadata/incidents \
  -H "Content-Type: application/json" \
  -d '{"packageId": 123, "username": "user@example.com", "password": "password123"}'
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.lsports.eu/u/engage/hyper-livescore/metadata-api-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.