> For the complete documentation index, see [llms.txt](https://syticks.gitbook.io/merpi-by-syticks/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://syticks.gitbook.io/merpi-by-syticks/api-reference/hospitality-ticketing-hotels-resorts-apartments/get-list-of-hotels-apartments-resorts.md).

# Get List of Hotels/Apartments/Resorts

#### GET `/v2/merpi/hotels`

## Query Parameters

| Parameter              | Type    | Required | Description                                                    |
| ---------------------- | ------- | -------- | -------------------------------------------------------------- |
| `business_id`          | string  | No       | Filter hotels by specific hospitality business                 |
| `city`                 | string  | No       | Filter by city name (e.g., "Ikeja", "Lagos", "Abuja")          |
| `state`                | string  | No       | Filter by state (e.g., "Lagos", "Abuja", "Kaduna")             |
| `country`              | string  | No       | Filter by country (default: "Nigeria")                         |
| `property_type`        | string  | No       | Filter by property type: `hotel`, `apartment`, `resort`, `inn` |
| `available_rooms_only` | boolean | No       | If `true`, only return hotels with available rooms             |
| `min_price`            | number  | No       | Minimum price per night (in Naira)                             |
| `max_price`            | number  | No       | Maximum price per night (in Naira)                             |
| `min_occupancy`        | number  | No       | Minimum guest capacity per room                                |
| `max_occupancy`        | number  | No       | Maximum guest capacity per room                                |
| `amenities`            | string  | No       | Comma-separated amenities (e.g., "wifi,pool,gym")              |
| `search`               | string  | No       | Search term for hotel name or description                      |
| `per_page`             | number  | No       | Number of results per page (default: 20)                       |
| `page`                 | number  | No       | Page number for pagination (default: 1)                        |

## Header Parameters

| Parameter           | Type   | Required | Description                                   |
| ------------------- | ------ | -------- | --------------------------------------------- |
| `X-API-KEY`         | string | Yes      | Your API key to access this endpoint          |
| `TransactionMedium` | string | Yes      | Transaction medium: `Web`, `Mobile`, or `POS` |

## Example Requests

**Basic request - Get all hotels:**

```bash
GET {{url}}/v2/merpi/hotels
```

**Filter by city:**

```bash
GET {{url}}/v2/merpi/hotels?city=Lagos
```

**Filter by city and property type:**

```bash
GET {{url}}/v2/merpi/hotels?city=Lagos&property_type=hotel
```

**Filter by price range:**

```bash
GET {{url}}/v2/merpi/hotels?min_price=20000&max_price=50000
```

**Filter by amenities:**

```bash
GET {{url}}/v2/merpi/hotels?amenities=wifi,pool,gym
```

**Only show hotels with available rooms:**

```bash
GET {{url}}/v2/merpi/hotels?available_rooms_only=true
```

**Complex filter - Lagos hotels with WiFi and pool, price range ₦20k-50k:**

```bash
GET {{url}}/v2/merpi/hotels?city=Lagos&property_type=hotel&available_rooms_only=true&min_price=20000&max_price=50000&amenities=wifi,pool&per_page=10
```

## Code Examples

```javascript
const response = await fetch('{{url}}/v2/merpi/hotels?city=Lagos&available_rooms_only=true', {
  method: 'GET',
  headers: {
    'X-API-KEY': 'your_api_key_here',
    'TransactionMedium': 'Web'
  }
});

const data = await response.json();
console.log(data);
```

**JavaScript - Axios**

```javascript
const axios = require('axios');

const response = await axios.get('{{url}}/v2/merpi/hotels', {
  params: {
    city: 'Lagos',
    available_rooms_only: true,
    min_price: 20000,
    max_price: 50000
  },
  headers: {
    'X-API-KEY': 'your_api_key_here',
    'TransactionMedium': 'Web'
  }
});

console.log(response.data);
```

**cURL**

```bash
curl -X GET "{{url}}/v2/merpi/hotels?city=Lagos&available_rooms_only=true" \
  -H "X-API-KEY: your_api_key_here" \
  -H "TransactionMedium: Web"
```

## Get list of hotels, apartments, and resorts

> This endpoint retrieves a paginated list of available hospitality properties including hotels, apartments, resorts, and inns. It supports extensive filtering by location, price range, amenities, availability, property type, and keyword search to help merchants discover relevant accommodations.<br>

```json
{"openapi":"3.0.3","info":{"title":"Syticks Hospitality API","version":"2.0.0"},"paths":{"/v2/merpi/hotels":{"get":{"summary":"Get list of hotels, apartments, and resorts","description":"This endpoint retrieves a paginated list of available hospitality properties including hotels, apartments, resorts, and inns. It supports extensive filtering by location, price range, amenities, availability, property type, and keyword search to help merchants discover relevant accommodations.\n","operationId":"getHotels","parameters":[{"name":"city","in":"query","required":false,"schema":{"type":"string"},"description":"Filter properties by city name."},{"name":"state","in":"query","required":false,"schema":{"type":"string"},"description":"Filter properties by state name."},{"name":"country","in":"query","required":false,"schema":{"type":"string"},"description":"Filter properties by country name."},{"name":"property_type","in":"query","required":false,"schema":{"type":"string","enum":["hotel","apartment","resort","inn"]},"description":"Filter by property type."},{"name":"min_price","in":"query","required":false,"schema":{"type":"integer"},"description":"Minimum room price to include."},{"name":"max_price","in":"query","required":false,"schema":{"type":"integer"},"description":"Maximum room price to include."},{"name":"amenities","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of amenities. Properties must have ALL specified amenities to be included.\n"},{"name":"available_rooms_only","in":"query","required":false,"schema":{"type":"boolean"},"description":"Only return properties with at least one available room."},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive keyword search on property name and description."},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer"},"description":"Number of results per page."}],"responses":{"200":{"description":"List of hotels, apartments, and resorts","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","properties":{"hotels":{"type":"array","items":{"$ref":"#/components/schemas/Hotel"}},"next_page":{"type":"string","nullable":true},"count":{"type":"integer"},"per_page":{"type":"integer"}}}}}}}}}}}},"components":{"schemas":{"Hotel":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"location":{"type":"string"},"description":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"coordinates":{"type":"object","properties":{"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true}}},"contact":{"type":"object","properties":{"website":{"type":"string"}}},"business":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"photo":{"type":"string","nullable":true},"slug":{"type":"string"},"type":{"type":"string"}}},"check_in_time":{"type":"string"},"check_out_time":{"type":"string"},"amenities":{"type":"array","items":{"type":"string"}},"images":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"image_url":{"type":"string"},"alt_text":{"type":"string"}}}},"property_type":{"type":"string","enum":["hotel","apartment","resort","inn"]},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}
```

## Response Fields

#### Root Level

| Field     | Type    | Description                                         |
| --------- | ------- | --------------------------------------------------- |
| `success` | boolean | Indicates if the request was successful             |
| `status`  | number  | HTTP status code (200 for success)                  |
| `message` | string  | Response message                                    |
| `data`    | object  | Response data containing hotels and pagination info |

#### Data Object

| Field       | Type         | Description                                      |
| ----------- | ------------ | ------------------------------------------------ |
| `hotels`    | array        | Array of hotel objects                           |
| `next_page` | number\|null | Next page number if available, null if last page |
| `count`     | number       | Total number of hotels matching filters          |
| `per_page`  | number       | Number of results per page                       |

#### Hotel Object

| Field            | Type   | Description                                      |
| ---------------- | ------ | ------------------------------------------------ |
| `id`             | number | Unique hotel identifier                          |
| `name`           | string | Hotel name                                       |
| `location`       | string | Full address of the property                     |
| `description`    | string | Hotel description and highlights                 |
| `city`           | string | City where hotel is located                      |
| `state`          | string | State where hotel is located                     |
| `country`        | string | Country (Nigeria)                                |
| `coordinates`    | object | GPS coordinates (latitude, longitude)            |
| `contact`        | object | Contact information (website)                    |
| business         | object | Business information(id, name, photo, type, etc) |
| `check_in_time`  | string | Standard check-in time                           |
| `check_out_time` | string | Standard check-out time                          |
| `amenities`      | array  | List of hotel amenities                          |
| `images`         | array  | Hotel images with URLs                           |
| `property_type`  | string | Type: `hotel`, `apartment`, `resort`, or `inn`   |
| `status`         | string | Hotel status (`active`, `inactive`)              |
| `created_at`     | string | Record creation timestamp (ISO 8601 format)      |
| `updated_at`     | string | Last update timestamp (ISO 8601 format)          |

#### Coordinates Object

| Field       | Type         | Description              |
| ----------- | ------------ | ------------------------ |
| `latitude`  | number\|null | GPS latitude coordinate  |
| `longitude` | number\|null | GPS longitude coordinate |

#### Contact Object

| Field     | Type         | Description       |
| --------- | ------------ | ----------------- |
| `website` | string\|null | Hotel website URL |

#### Business Object

| Field | Type   | Description                                                                                                                  |
| ----- | ------ | ---------------------------------------------------------------------------------------------------------------------------- |
| id    | string | ID of hospitality business                                                                                                   |
| name  | string | Name of hospitality business                                                                                                 |
| photo | string | Logo of Hospitality Business                                                                                                 |
| type  | string | Type of business(which is always going to be hospitality). We have other business categories like Transport & Entertainment. |
| slug  | string | slug of hospitality business                                                                                                 |

#### Image Object

| Field       | Type   | Description                    |
| ----------- | ------ | ------------------------------ |
| `id`        | number | Image identifier               |
| `image_url` | string | Full URL to the image          |
| `alt_text`  | string | Alternative text for the image |

## Common Use Cases

**1. Browse all hotels**

```javascript
GET /v2/merpi/hotels
```

Use this to display all available hotels without any filters.

***

**2. Find hotels in a specific city**

```javascript
GET /v2/merpi/hotels?city=Abuja
```

Perfect for location-based searches when users specify their destination.

***

**3. Search for budget hotels**

```javascript
GET /v2/merpi/hotels?min_price=15000&max_price=30000
```

Filter hotels by price range to match user budget.

***

**4. Find hotels with specific amenities**

```javascript
GET /v2/merpi/hotels?amenities=wifi,pool,restaurant
```

Show hotels that have all specified amenities.

***

**5. Search by hotel name**

```javascript
GET /v2/merpi/hotels?search=Grand Paradise
```

Search for hotels by name or keywords in their description.

***

**6. Only show hotels with available rooms**

```javascript
GET /v2/merpi/hotels?available_rooms_only=true
```

Filter out fully booked hotels to show only properties with availability.

***

**7. Complex filtered search**

```javascript
GET /v2/merpi/hotels?city=Lagos&property_type=hotel&available_rooms_only=true&min_price=20000&max_price=50000&amenities=wifi,pool
```

Combine multiple filters for precise results.

## Important Notes

**Pagination:** Use `page` and `per_page` parameters to navigate through results. Check `next_page` field to determine if more pages are available.

**Amenities Filtering:** When filtering by amenities, use comma-separated values without spaces (e.g., `wifi,pool,gym`). Hotels must have ALL specified amenities to appear in results.

**Property Types:** Valid values are `hotel`, `apartment`, `resort`, and `inn`.

**Price Filtering:** `min_price` and `max_price` filter based on room prices, not hotel-level pricing. Hotels are included if they have at least one room within the specified price range.

**Search Parameter:** The `search` parameter looks for matches in hotel names and descriptions. It's case-insensitive.

## Next Steps

After retrieving the hotel list, you typically:

1. Display hotels to your users with key information (name, location, price range, amenities)
2. When a user selects a hotel, call [**Get Hotel Rooms**](/merpi-by-syticks/api-reference/hospitality-ticketing-hotels-resorts-apartments/get-hotel-apartment-resort-rooms.md) to fetch available room types
3. Alternatively, use [**Get Hotels & Rooms in One Endpoint**](/merpi-by-syticks/api-reference/hospitality-ticketing-hotels-resorts-apartments/get-hotel-and-rooms-in-one-endpoint.md) to get hotel and room data in one call
4. Finally, proceed to [**Book Hotel Room**](/merpi-by-syticks/api-reference/hospitality-ticketing-hotels-resorts-apartments/book-hotel-apartment-room-tickets.md) to complete the reservation


---

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

```
GET https://syticks.gitbook.io/merpi-by-syticks/api-reference/hospitality-ticketing-hotels-resorts-apartments/get-list-of-hotels-apartments-resorts.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.