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

# Reference inventory statistics by country and city

> Query global hotel counts and per-country breakdowns from the Mapping.Travel reference inventory, including city-level detail for globe visualizations.

The statistics endpoints expose aggregated hotel counts across the reference inventory. You can retrieve a global summary, a ranked list of countries, or city-level detail for a specific country. These endpoints are designed to support globe or map visualizations, dashboards, and coverage reporting.

***

## GET /api/v1/reference/statistics

Retrieve global statistics across the entire reference inventory, including hotel counts broken down by country and city.

```bash theme={null} theme={null}
GET https://api.mapping.travel/api/v1/reference/statistics
```

### Response

<ResponseField name="totalHotels" type="number" required>
  Total number of reference hotels in the inventory.
</ResponseField>

<ResponseField name="totalCountries" type="number" required>
  Number of distinct countries represented.
</ResponseField>

<ResponseField name="totalCities" type="number" required>
  Number of distinct cities represented.
</ResponseField>

<ResponseField name="byCountry" type="object[]">
  List of countries with their hotel counts.

  <Expandable title="country entry properties">
    <ResponseField name="country" type="string">
      Country name.
    </ResponseField>

    <ResponseField name="hotelCount" type="number">
      Number of reference hotels in this country.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example

```bash theme={null} theme={null}
curl https://api.mapping.travel/api/v1/reference/statistics
```

```json theme={null} theme={null}
{
  "totalHotels": 1284500,
  "totalCountries": 192,
  "totalCities": 48320,
  "byCountry": [
    { "country": "United States", "hotelCount": 142300 },
    { "country": "Germany", "hotelCount": 87400 }
  ]
}
```

***

## GET /api/v1/reference/statistics/countries

Retrieve countries ranked by hotel count.

```bash theme={null} theme={null}
GET https://api.mapping.travel/api/v1/reference/statistics/countries
```

### Query parameters

<ParamField query="limit" type="number" default="20">
  Maximum number of countries to return. Clamped to 1–200.
</ParamField>

### Response

Returns an array of country statistics objects, sorted descending by hotel count.

<ResponseField name="country" type="string" required>
  Country name.
</ResponseField>

<ResponseField name="hotelCount" type="number" required>
  Number of reference hotels in this country.
</ResponseField>

### Example

```bash theme={null} theme={null}
curl "https://api.mapping.travel/api/v1/reference/statistics/countries?limit=10"
```

```json theme={null} theme={null}
[
  { "country": "United States", "hotelCount": 142300 },
  { "country": "Germany", "hotelCount": 87400 },
  { "country": "France", "hotelCount": 74100 }
]
```

***

## GET /api/v1/reference/statistics/countries/{country}

Retrieve detailed statistics for a single country, including a breakdown of hotel counts per city.

```bash theme={null} theme={null}
GET https://api.mapping.travel/api/v1/reference/statistics/countries/{country}
```

### Path parameters

<ParamField path="country" type="string" required>
  Country name. Must match the name as it appears in the inventory (e.g. `France`, `United States`).
</ParamField>

### Response

<ResponseField name="country" type="string" required>
  Country name.
</ResponseField>

<ResponseField name="totalHotels" type="number" required>
  Total hotel count for this country.
</ResponseField>

<ResponseField name="cities" type="object[]" required>
  List of cities in this country with their hotel counts.

  <Expandable title="city entry properties">
    <ResponseField name="city" type="string">
      City name.
    </ResponseField>

    <ResponseField name="hotelCount" type="number">
      Number of hotels in this city.
    </ResponseField>
  </Expandable>
</ResponseField>

### Errors

| Status          | Description                                           |
| --------------- | ----------------------------------------------------- |
| `404 Not Found` | The specified country was not found in the inventory. |

### Example

```bash theme={null} theme={null}
curl "https://api.mapping.travel/api/v1/reference/statistics/countries/France"
```

```json theme={null} theme={null}
{
  "country": "France",
  "totalHotels": 74100,
  "cities": [
    { "city": "Paris", "hotelCount": 12400 },
    { "city": "Lyon", "hotelCount": 5300 },
    { "city": "Marseille", "hotelCount": 4800 }
  ]
}
```

<Note>
  Country names are case-sensitive and must match the inventory's stored form. Use `GET /api/v1/reference/statistics/countries` first to discover the exact country names available.
</Note>