> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mrdoge.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Regions

> Get all available regions (countries) with sports coverage, competition counts, and localized names

<Info>
  **Public Endpoint**: No API key required
</Info>

This endpoint returns all regions where Mr. Doge has sports coverage, including:

* Localized region names (supports `en`, `es`, `pt`)
* Number of competitions per region
* Number of events (filtered by query parameters)
* Available sports in each region
* List of competitions with sport references

Perfect for building region selectors or filtering events by location.

## Query Parameters

<ParamField query="locale" type="string" default="en">
  Language code for localized region names. Supported: `en`, `es`, `pt`
</ParamField>

<ParamField query="date" type="string">
  Filter regions with events on specific date (YYYY-MM-DD format)

  Example: `2025-11-08`

  <Warning>
    Cannot be used together with `startDate` or `endDate`. Choose either `date` for single-day filtering or `startDate`/`endDate` for range filtering.
  </Warning>
</ParamField>

<ParamField query="startDate" type="string">
  Filter regions with events starting from this date

  <Warning>
    Cannot be used together with `date` parameter.
  </Warning>
</ParamField>

<ParamField query="endDate" type="string">
  Filter regions with events ending on this date

  <Warning>
    Cannot be used together with `date` parameter.
  </Warning>
</ParamField>

<ParamField query="status" type="string" default="upcoming,live">
  Filter by event status (repeat or comma-separate values). Use `status=completed` to inspect historical dates.
</ParamField>

<ParamField query="timezone" type="string">
  Timezone for date filtering

  Example: `America/New_York`, `Europe/London`
</ParamField>

## Response

Returns an object with a `data` array containing region objects.

<ResponseField name="data" type="array">
  <Expandable title="Region Object">
    <ResponseField name="id" type="integer">
      Region ID
    </ResponseField>

    <ResponseField name="caption" type="string">
      Region name (localized based on `locale` parameter)
    </ResponseField>

    <ResponseField name="_count" type="object">
      <Expandable title="Count Object">
        <ResponseField name="competitions" type="integer">
          Number of competitions in this region
        </ResponseField>

        <ResponseField name="events" type="integer">
          Number of events in this region (based on applied filters)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="availableSports" type="array">
      Array of sport objects with `id` and `name`

      <Expandable title="Sport Object">
        <ResponseField name="id" type="integer">
          Sport ID for filtering and referencing
        </ResponseField>

        <ResponseField name="name" type="string">
          Sport name (e.g., "soccer", "basketball", "tennis")
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="competitions" type="array">
      Array of competition objects with `id`, `caption`, and `sportId`

      <Expandable title="Competition Object">
        <ResponseField name="id" type="integer">
          Competition ID
        </ResponseField>

        <ResponseField name="caption" type="string">
          Competition name
        </ResponseField>

        <ResponseField name="sportId" type="integer">
          Reference to sport ID from availableSports array
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Request

```bash theme={null}
curl https://api.mrdoge.co/v2/regions?locale=en&date=2025-11-08
```

## Example Response

```json theme={null}
{
  "data": [
    {
      "id": 1,
      "caption": "World",
      "_count": {
        "competitions": 1,
        "events": 10
      },
      "availableSports": [
        {
          "id": 1,
          "name": "soccer"
        },
      ],
      "competitions": [
        {
          "id": 39,
          "caption": "World Cup",
          "sportId": 1
        },
      ]
    }
  ]
}
```

## Use Cases

<CardGroup cols={2}>
  <Card title="Region Selector" icon="globe">
    Build a dropdown to let users filter events by country
  </Card>

  <Card title="Coverage Map" icon="map">
    Display which regions have the most events and competitions
  </Card>

  <Card title="Localization" icon="language">
    Show region names in user's preferred language
  </Card>

  <Card title="Sport Filtering" icon="filter">
    Show which regions have specific sports available
  </Card>
</CardGroup>


## OpenAPI

````yaml /api-reference/openapi.json GET /v2/regions
openapi: 3.1.0
info:
  title: Mr. Doge API
  description: >-
    Comprehensive sports betting odds, AI predictions, and live data API
    covering 8 major sports with real-time updates and value betting
    recommendations.
  version: 1.0.0
  contact:
    name: Mr. Doge Support
    email: support@mrdoge.co
    url: https://mrdoge.co
servers:
  - url: https://api.mrdoge.co
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: Odds
    description: Endpoints for accessing sports events, odds, and betting markets
  - name: AI
    description: AI-powered betting recommendations and value opportunities
paths:
  /v2/regions:
    get:
      tags:
        - Odds
      summary: List Regions
      description: >-
        Get all available regions (countries) with sports coverage, competition
        counts, and localized names.
      parameters:
        - name: locale
          in: query
          description: Language code for localized region names
          schema:
            type: string
            default: en
            example: en
        - name: date
          in: query
          description: Filter regions with events on specific date (YYYY-MM-DD)
          schema:
            type: string
            format: date
            example: '2025-11-08'
        - name: startDate
          in: query
          description: Filter regions with events starting from this date
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          description: Filter regions with events ending on this date
          schema:
            type: string
            format: date
        - name: status
          in: query
          description: >-
            Filter regions by event status (repeat or comma-separate values).
            Defaults to upcoming and live events.
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
              enum:
                - upcoming
                - live
                - completed
        - name: timezone
          in: query
          description: Timezone for date filtering
          schema:
            type: string
            example: America/New_York
      responses:
        '200':
          description: List of regions
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Region'
      security: []
components:
  schemas:
    Region:
      type: object
      properties:
        id:
          type: integer
          example: 1
        caption:
          type: string
          example: England
        _count:
          type: object
          properties:
            competitions:
              type: integer
              example: 5
            events:
              type: integer
              example: 120
        availableSports:
          type: array
          items:
            type: string
          example:
            - soccer
            - tennis
        competitions:
          type: array
          items:
            $ref: '#/components/schemas/Competition'
    Competition:
      type: object
      properties:
        id:
          type: integer
          example: 1
        caption:
          type: string
          example: Premier League
        regionId:
          type: integer
          example: 1
        region:
          $ref: '#/components/schemas/Region'
        _count:
          type: object
          properties:
            events:
              type: integer
              example: 38
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Use your API key from the Mr. Doge dashboard. Format: `Bearer
        sk_live_...` or `Bearer sk_test_...`

````