Get List of Hotels

Retrieve a list of available hotels, apartments, and resorts. This endpoint supports extensive filtering options to help merchants discover relevant accommodations based on location, price, amenities,

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:

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

Filter by city:

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

Filter by city and property type:

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

Filter by price range:

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

Filter by amenities:

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

Only show hotels with available rooms:

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

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

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 - Fetch

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

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

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

Response

Success Response (200)

{
    "success": true,
    "status": 200,
    "message": "List of hotels",
    "data": {
        "hotels": [
            {
                "id": 2,
                "name": "Stay IN Apartments, Ikeja",
                "location": "12. Allen Avenue, Ikeja",
                "description": "Stay IN Properties & Apartments is the brand that speaks luxury and affordability in one breath.",
                "city": "Ikeja",
                "state": "Lagos",
                "country": "Nigeria",
                "coordinates": {
                    "latitude": null,
                    "longitude": null
                },
                "contact": {
                    "website": "https://syticks.com"
                },
                "business": {
                    "id": "abd5b9d4-f98f-483c-b0a4-eaadcdc776fa",
                    "name": "Stay-IN",
                    "photo": null,
                    "slug": "stay-in",
                    "type": "hospitality"
                },
                "check_in_time": "12PM",
                "check_out_time": "12PM",
                "amenities": [
                    "Gym",
                    "Parking space",
                    "Buffet"
                ],
                "images": [
                    {
                        "id": 20,
                        "image_url": "https://dev.syticks.com/storage/HotelPhotos/hdrAuepW4uf8FWqrKRCvJogTgyZcit0DCezy7PWG.jpg",
                        "alt_text": "Hotel Image"
                    }
                ],
                "property_type": "hotel",
                "status": "active",
                "created_at": "2025-09-07T21:17:17.000000Z",
                "updated_at": "2026-01-07T20:22:45.000000Z"
            },
            {
                "id": 16,
                "name": "Grand Paradise Hotel",
                "location": "Downtown City",
                "description": "A luxurious hotel with modern amenities.",
                "city": "Lagos",
                "state": "Lagos",
                "country": "Nigeria",
                "coordinates": {
                    "latitude": 6.5244,
                    "longitude": 3.3792
                },
                "contact": {
                    "website": "https://grandparadise.com"
                },
                "business": {
                    "id": "abd5b9d4-f98f-483c-b0a4-eaadcdc776fa",
                    "name": "Stay-IN",
                    "photo": null,
                    "slug": "stay-in",
                    "type": "hospitality"
                },
                "check_in_time": "2PM",
                "check_out_time": "11AM",
                "amenities": [
                    "Pool",
                    "Spa",
                    "Restaurant"
                ],
                "images": [
                {
                        "id": 20,
                        "image_url": "https://dev.syticks.com/storage/HotelPhotos/hdrAuepW4uf8FWqrKRCvJogTgyZcit0DCezy7PWG.jpg",
                        "alt_text": "Hotel Image"
                    }
                ],
                "property_type": "hotel",
                "status": "active",
                "created_at": "2025-09-07T23:26:12.000000Z",
                "updated_at": "2025-09-09T22:07:11.000000Z"
            }
        ],
        "next_page": null,
        "count": 12,
        "per_page": 20
    }
}

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

GET /v2/merpi/hotels

Use this to display all available hotels without any filters.

---

2. Find hotels in a specific city

GET /v2/merpi/hotels?city=Abuja

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

---

3. Search for budget hotels

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

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

Show hotels that have all specified amenities.

---

5. Search by hotel name

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

Search for hotels by name or keywords in their description.

---

6. Only show hotels with available rooms

GET /v2/merpi/hotels?available_rooms_only=true

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

---

7. Complex filtered search

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 to fetch available room types

3. Alternatively, use Get Hotels & Rooms in One Endpoint to get hotel and room data in one call

4. Finally, proceed to Book Hotel Room to complete the reservation