Endpoint vs Entity

Difference between an Endpoint and an Entity

When working with the Sportmonks Football API, you’ll encounter both endpoints and entities. These two concepts are closely related but serve different purposes. Understanding the difference between them is key to designing efficient requests and interpreting responses correctly.

What is an Endpoint?

An endpoint is a specific API URL that you call to retrieve or send data. It defines where and how you can access the data.

Endpoints:

• Represent actions or data-access points in the API.

• Are used to make requests (GET, POST, etc.) via a structured URL.

• Usually include filters, includes, and query parameters to refine or expand the response.

Example:

GET /v3/football/fixtures/19101794?api_token=YOUR_TOKEN&include=events,statistics

This endpoint retrieves details for a single fixture, including related events and statistics.

Common endpoint examples:

• /fixtures : To get match information.

• /teams : To list or look up teams.

• /players : To fetch player data.

• /standings/seasons/{season_id} : To view a season’s table.

Each endpoint returns one or more entities.

What is an Entity?

An entity represents a type of data object that exists within the Sportmonks data model. It describes what the data is, such as a Fixture, Team, Player, or League.

Entities:

• Are objects that appear in API responses.

• Have a consistent structure (fields, attributes, and relationships).

• Are often linked to one another (for example, a Fixture includes Team and Venue entities).

Example Entity Structure (Fixture):

{
  "id": 19101794,
  "name": "Borussia Dortmund vs Real Madrid",
  "starting_at": "2024-06-01 19:00:00",
  "venue": {
    "id": 1,
    "name": "Wembley Stadium",
    "city": "London"
  },
  "participants": [
    { "id": 68, "name": "Borussia Dortmund" },
    { "id": 3468, "name": "Real Madrid" }
  ]
}

Here, the Fixture entity contains Venue and Team (Participant) entities as nested objects.

The relationship between Endpoints and Entities

You can think of it like this:

Concept	Purpose	Example
Endpoint	The URL you call to get or send data	/fixtures/19101794
Entity	The data structure returned by the endpoint	Fixture, which includes Team, Venue, and Event entities
Analogy	Endpoint = door handle, Entity = the room inside	The handle lets you enter, but the room contains the data

---

Examples from the Football API

• Calling the Fixtures endpoint returns Fixture entities.

• Calling the Teams endpoint returns Team entities.

• Including statistics or lineups in your query adds Statistic or Lineup entities to the response.

• Calling the Standings endpoint returns Standing entities, often containing nested Team and League data.

Example combined request:

GET /v3/football/fixtures?include=participants,venue,statistics

This single endpoint returns multiple entities (Fixture, Team, Venue, Statistic).

Why the distinction matters

• Documentation navigation: Each endpoint page tells you how to get the data. Each entity page tells you what fields you’ll receive.

• Database design: Understanding entities helps when modelling your local storage schema.

• Includes and relations: You’ll often “include” extra entities within an endpoint call. Knowing their structure ensures efficient queries.

Summary

Term	Description	Example
Endpoint	A path you call in the API to request or send data	/v3/football/fixtures/19101794
Entity	The object type representing actual data in the response	Fixture, Team, Player, League
Relationship	Endpoints deliver entities	The Fixtures endpoint returns Fixture entities (which can include Teams, Venues, etc.)