# Venues

> **🏎️ Motorsport API Required**
>
> All Venues endpoints require an active Motorsport API subscription (€79/mo, 3,000 API calls/hr).
>
> [View pricing →](https://www.sportmonks.com/formula-one-api/)

A **venue** represents a physical racing circuit where motorsport fixtures take place - for example, Circuit de Monaco or Silverstone Circuit. A venue is the track itself and is distinct from the [Stage](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/stages) (race weekend) that takes place there. The same circuit can host race weekends across multiple seasons.

{% hint style="info" %}
Use the Venues endpoints to retrieve circuit profiles, display track layouts and location data, or list all circuits on a season calendar.

Use the `metadata` include to enrich venue responses with detailed track information such as track length, direction, surface type, DRS zones, and number of turns. The type reference for these details is described in the [Metadata & Per-Season Data Type Reference](https://docs.sportmonks.com/v3/motorsport-api/welcome/metadata-and-per-season-data-type-reference). 
{% endhint %}

#### **Available endpoints**

* [**GET All Venues**](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/venues/get-all-venues): returns all venues (racing circuits) available in the Motorsport API.
* [**GET Venue by ID**](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/venues/get-venues-by-id): returns a single venue by its ID.
* [**GET Venues by Search**](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/venues/get-venues-by-search): returns venues matching a provided search query.
* [**GET Venues by Season ID**](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/venues/get-venues-by-season-id): returns all venues on the calendar for a provided season ID.

#### **Include options**

You can enrich venue responses using `include`:

[`country`](https://docs.sportmonks.com/v3/core-api/entities/core#country), [`city`](https://docs.sportmonks.com/v3/core-api/entities/core#city), [`fixtures`](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/fixture), `metadata`

{% hint style="info" %}
Want to keep responses lighter and faster? Use `select` to request only the fields you need. See: [Request options](https://docs.sportmonks.com/v3/motorsport-api/welcome/request-options)
{% endhint %}

#### **Using `metadata`**

The `metadata` include adds track-specific data not present in the base response, including track length, direction (clockwise or anti-clockwise), circuit type (race circuit or street circuit), Grand Prix name, DRS zone count, and number of turns. Resolve the exact type values via the [Metadata & Per-Season Data Type Reference](https://docs.sportmonks.com/v3/motorsport-api/welcome/metadata-and-per-season-data-type-reference).

#### **Using `city`**

The base response includes a `city_name` field, but this is sparsely populated and may be `null` even when `city_id` is present. Use `?include=city` for reliable city data.

> **Include depth:** Venues endpoints support a maximum of **2** nested includes.

#### **Working with venue fields**

* **`image_path`** - returns a **track layout diagram**, not a photograph of the venue. This is the circuit map image suitable for displaying alongside race weekend previews and venue profiles.
* **`latitude`** / **`longitude`** - geographic coordinates of the circuit as strings. Parse to float before passing to a mapping library.
* **`capacity`** - spectator/grandstand capacity. Useful for venue profile pages.
* **`surface`** - the track surface material. For F1 circuits this is always `"asphalt"`.
* **`city_name`** - sparsely populated. Use `?include=city` instead for reliable city data.
* **`address`** / **`zipcode`** - sparsely populated. Handle `null` values in your application.
* **`national_team`** - not used in the Motorsport API. Inherited from the shared v3 response structure and can be safely ignored.

#### **Venues vs Stages**

It is worth being clear on the distinction between a venue and a stage when building location-based features:

|                     | Venue                                       | Stage                                  |
| ------------------- | ------------------------------------------- | -------------------------------------- |
| Represents          | The physical circuit                        | The race weekend event                 |
| Changes per season? | No - circuits are permanent                 | Yes - new stages each season           |
| Has fixtures?       | Via `?include=fixtures`                     | Via `?include=fixtures`                |
| Best for            | Circuit profiles, track maps, location data | Race weekend schedules, event metadata |

A stage's venue is accessible via `?include=venue` on the [Stages](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/stages) or [Fixtures](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/fixtures) endpoints.

#### **Common requests**

**Full circuit profile with track data:**

```http
GET /v3/motorsport/venues/VENUE_ID
?api_token=YOUR_TOKEN&include=metadata;country;city
```

**Search for a circuit by name:**

```http
GET /v3/motorsport/venues/search/monaco?api_token=YOUR_TOKEN
```

**All circuits on this season's calendar:**

```http
GET /v3/motorsport/venues/seasons/SEASON_ID
?api_token=YOUR_TOKEN&include=metadata
```

**Lightweight circuit list (name, layout image, and coordinates):**

```http
GET /v3/motorsport/venues/seasons/SEASON_ID
?api_token=YOUR_TOKEN&select=id,name,image_path,latitude,longitude
```

#### **Related entities**

Get an overview and explanation of all the fields returned in the API response:

* [Venue](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/venue)

#### **Related pages**

* [Stages](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/stages) - Race weekends held at a venue, accessible via `?include=venue` on stages
* [Fixtures](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/fixtures) - Sessions held at a venue, accessible via `?include=venue` on fixtures
* [Seasons](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/seasons) - Look up season IDs for the by-season endpoint
* [Metadata & Per-Season Data Type Reference](https://docs.sportmonks.com/v3/motorsport-api/welcome/metadata-and-per-season-data-type-reference)


---

# Agent Instructions: 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:

```
GET https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/venues.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.