# Getting Started

With this Hotel API, you can get prices of all the hotels around the world from the top 200 OTAs. You just have to make a single GET request and all this data will be returned to you in JSON form.

All REST API calls will return `JSON` results.

The basic API URL is: `https://api.makcorps.com/`

1. Each request should contain an API key or a JWT Token. This will help us to identify your account.
2. If you exceed your plan connection limit, the API will respond with a 403 error.
3. Each GET request will return a JSON response with a 200 response code.
4. 404 error occurs when either there is no data available for your query or your API key is wrong.

| Error Codes | Description                          |
| ----------- | ------------------------------------ |
| 200         | Request Successfull                  |
| 404         | No Data available or user not found. |

### Video Tutorial

{% embed url="<https://www.youtube.com/watch?v=rL44vrWLRgA>" %}


# JWT Token API

If you are using our trial pack then you will need this token in order to access the /free endpoint.

API endpoint for this API is: `https://api.makcorps.com/auth`

### Guide

Your request to our `/free` endpoint is authenticated using this JWT token. You will need your username and password in order to access this `/auth` API.

You can find your username and password in the email you might have received while signing up on our website.

|          |                             |
| -------- | --------------------------- |
| Username | Usernames used while signup |
| Password | Password used while signup  |

### Usage

You have to send a POST request to <https://api.makcorps.com/auth> along with your username and password in the JSON body. Along with this, you have to send a header where the key will be `Content-Type` and its value will be `application/json`.

{% tabs %}
{% tab title="Curl" %}

```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }' \
  https://api.makcorps.com/auth

```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import json

url = "https://api.makcorps.com/auth"
payload = {
    "username": "your_username",
    "password": "your_password"
}

headers = {
    "Content-Type": "application/json"
}

response = requests.post(url, data=json.dumps(payload), headers=headers)

# Print the response
print(response.json())

```

{% endtab %}

{% tab title="Nodejs" %}

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

const url = 'https://api.makcorps.com/auth';
const payload = {
  username: 'your_username',
  password: 'your_password'
};

const headers = {
  'Content-Type': 'application/json'
};

axios.post(url, payload, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error);
  });
```

{% endtab %}
{% endtabs %}

### Response

The API response will look like this.

```
{'access_token': 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2ODcyNjc5NzIsImlhdCI6MTY4NzI2NjE3MiwibmJmIjoxNjg3MjY2MTcyLCJpZGVudGl0eSI6MjExMH0.HqBtNdrOg21LzKY7RmylIQpdazFx5QZSVyhhYSs6qFA'}
```

{% hint style="info" %}
Now, you can use this JWT token inside your free Hotel API.&#x20;
{% endhint %}


# Free Hotel API

This is the free hotel API that anyone can access. Using this Hotel API you will get JSON data with hotel pricing from multiple vendors for any random future date.

API endpoint for this API is: `https://api.makcorps.com/free`

### Guide

You can pass the name of any city from any country to this API and our API will respond results according to that.&#x20;

> **This API has some limitations which has been discussed at the bottom of this page.**

Here is the list of parameters you have to pass to this API:

| Parameters | Description      |
| ---------- | ---------------- |
| city       | Name of the city |

### Usage

You have to send a GET request to <https://api.makcorps.com/auth> along with the name of the city and the JWT token you might have received from the [JWT Token API](/jwt-token-api).

{% tabs %}
{% tab title="Curl" %}

```bash
curl -X GET \
  -H "Authorization: JWT eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1MTc2NzczNjAsImlkZW50aXR5IjozLCJuYmYiOjE1MTc2NzczNjAsImV4cCI6MTUxNzY3OTE2MH0.ytSqQj3VDymEaJz9EIdskWELwDQZRD1Dbo6TuHaPz9U" \
  https://api.makcorps.com/free/london

```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = 'https://api.makcorps.com/free/london'
headers = {
    'Authorization': 'JWT eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1MTc2NzczNjAsImlkZW50aXR5IjozLCJuYmYiOjE1MTc2NzczNjAsImV4cCI6MTUxNzY3OTE2MH0.ytSqQj3VDymEaJz9EIdskWELwDQZRD1Dbo6TuHaPz9U'
}

response = requests.get(url, headers=headers)

# Print the response
print(response.json())

```

{% endtab %}

{% tab title="Nodejs" %}

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

const url = 'https://api.makcorps.com/free/london';
const headers = {
  'Authorization': 'JWT eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1MTc2NzczNjAsImlkZW50aXR5IjozLCJuYmYiOjE1MTc2NzczNjAsImV4cCI6MTUxNzY3OTE2MH0.ytSqQj3VDymEaJz9EIdskWELwDQZRD1Dbo6TuHaPz9U'
};

axios.get(url, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error);
  });

```

{% endtab %}
{% endtabs %}

### Response

The sample response of the API will look somewhat like this.

```json
[
      {
        "hotelName": "ITC Grand Central, Mumbai - a Luxury Collection Hotel",
        "hotelId": "503409"
      },
      [
        {
          "price1": "180",
          "tax1": "27",
          "vendor1": "Booking.com"
        },
        {
          "price2": "180",
          "tax2": "27",
          "vendor2": "Hotels.com"
        },
        {
          "price3": "182",
          "tax3": "29",
          "vendor3": "StayForLong"
        },
        {
          "price4": "153",
          "tax4": "0",
          "vendor4": "Priceline"
        }
      ]
    ],
    [
      {
        "hotelName": "Bloom Hotel - Worli",
        "hotelId": "23526565"
      },
      [
        {
          "price1": "78",
          "tax1": "8",
          "vendor1": "Booking.com"
        },
        {
          "price2": "77",
          "tax2": "0",
          "vendor2": "Priceline"
        },
        {
          "price3": "86",
          "tax3": "9",
          "vendor3": "Trip.com"
        },
        {
          "price4": null,
          "tax4": null,
          "vendor4": "Vio.com"
        }
      ]
    ],
    [
      {
        "hotelName": "Bloom Hotel - Juhu",
        "hotelId": "23337279"
      },
      [
        {
          "price1": "72",
          "tax1": "8",
          "vendor1": "Booking.com"
        },
        {
          "price2": "90",
          "tax2": "10",
          "vendor2": "Hotels.com"
        },
        {
          "price3": "94",
          "tax3": "13",
          "vendor3": "StayForLong"
        },
        {
          "price4": "79",
          "tax4": "8",
          "vendor4": "Trip.com"
        }
      ]
    ],
    [
      {
        "hotelName": "The Oberoi Mumbai",
        "hotelId": "304225"
      },
      [
        {
          "price1": "204",
          "tax1": "31",
          "vendor1": "Booking.com"
        },
        {
          "price2": "204",
          "tax2": "31",
          "vendor2": "Hotels.com"
        },
        {
          "price3": "209",
          "tax3": "35",
          "vendor3": "StayForLong"
        },
        {
          "price4": "173",
          "tax4": "0",
          "vendor4": "Priceline"
        }
      ]
    ],
    [
      {
        "hotelName": "Radisson Blu Mumbai International Airport",
        "hotelId": "21362523"
      },
      [
        {
          "price1": "202",
          "tax1": "31",
          "vendor1": "Booking.com"
        },
        {
          "price2": "202",
          "tax2": "31",
          "vendor2": "Hotels.com"
        },
        {
          "price3": "202",
          "tax3": "31",
          "vendor3": "Expedia.com"
        },
        {
          "price4": "171",
          "tax4": "0",
          "vendor4": "Priceline"
        }
      ]
    ],
    [
      {
        "hotelName": "The Fern - Goregaon",
        "hotelId": "11774410"
      },
      [
        {
          "price1": "223",
          "tax1": "34",
          "vendor1": "Hotels.com"
        },
        {
          "price2": "220",
          "tax2": "20",
          "vendor2": "StayForLong"
        },
        {
          "price3": "180",
          "tax3": "28",
          "vendor3": "Trip.com"
        },
        {
          "price4": "165",
          "tax4": "25",
          "vendor4": "Agoda.com"
        }
      ]
    ],
```

### Understand the Response

| Properties | Description                            |
| ---------- | -------------------------------------- |
| price      | Price offered by the vendor            |
| vendor     | Name of the vendor                     |
| tax        | Tax you will be charged at the booking |
| hotelName  | Name of the hotel                      |
| hoteId     | Id of the hotel in our system          |

### Limitations of this API

Since this is the free version of our API therefore this API has some limitations.

* You will get rates for any random future dates because users will not be able to pass check-in and check-out dates to this API.
* You will only get 30 hotels for any city.&#x20;
* You cannot pass pax count like the number of adults or the number of rooms in this API.

{% hint style="info" %}
If you want to bypass these limitations then you have to gain access to our premium APIs. You can sign up for our premium APIs or if you want to test those APIs before signing up then you can contact us [here](https://share.hsforms.com/1A-iwjye2SwWRv4VHhQbBqg439wf). Remember we provide access to companies only.
{% endhint %}


# Hotel API - Search by City Name

In a single API request to this API will return all the hotels in a city with top 4 cheapest vendors.

API endpoint for this API is: `https://api.makcorps.com/citysearch`

### Guide

This API does not require a JWT token because you need your own personal API key to access this API. You can [contact us](https://share.hsforms.com/1A-iwjye2SwWRv4VHhQbBqg439wf) if you need API keys to this API.&#x20;

Here is the list of default parameters you have to use with this API:

| Parameters                                                              | Description                                                                          |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| <p>cityname<br><br><mark style="color:red;">required</mark></p>         | Name of the city                                                                     |
| <p>page<br><br><mark style="color:red;">required</mark></p>             | It is a page number. It starts with 0 and each page will provide you with 30 hotels. |
| <p>currency<br><br><mark style="color:red;">required</mark></p>         | It could be any currency like USD, INR, EUR, etc.                                    |
| <p>num\_of\_rooms<br><br><mark style="color:red;">required</mark></p>   | It is the number of rooms.                                                           |
| <p>num\_of\_adults<br><br><mark style="color:red;">required</mark></p>  | It is the number of adults.                                                          |
| <p>check\_in\_date<br><br><mark style="color:red;">required</mark></p>  | <p>It is the check-in date.<br><br>Format - YYYY-MM-DD</p>                           |
| <p>check\_out\_date<br><br><mark style="color:red;">required</mark></p> | <p>It is the check-out date.<br><br>Format - YYYY-MM-DD</p>                          |

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET "https://api.makcorps.com/citysearch/{cityname}/{page}/{currency}/{num_of_rooms}/{num_of_adults}/{check_in_date}/{check_out_date}?api_key=YOUR-API-KEY"
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = 'https://api.makcorps.com/citysearch/{cityname}/{page}/{currency}/{num_of_rooms}/{num_of_adults}/{check_in_date}/{check_out_date}'
api_key = 'YOUR-API-KEY'

url = url.format(
    cityname='London',
    page='0',
    currency='USD',
    num_of_rooms='1',
    num_of_adults='3',
    check_in_date='2023-10-03',
    check_out_date='2023-10-04'
)

url_with_api_key = f"{url}?api_key={api_key}"

response = requests.get(url_with_api_key)

# Print the response
print(response.json())
```

{% endtab %}

{% tab title="Nodejs" %}

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

const url = 'https://api.makcorps.com/citysearch/{cityname}/{page}/{currency}/{num_of_rooms}/{num_of_adults}/{check_in_date}/{check_out_date}';
const apiKey = 'YOUR-API-KEY';

const cityname = 'London';
const page = '0';
const currency = 'USD';
const num_of_rooms = '1';
const num_of_adults = '3';
const check_in_date = '2023-10-03';
const check_out_date = '2023-10-04';

const formattedUrl = url
  .replace('{cityname}', cityname)
  .replace('{page}', page)
  .replace('{currency}', currency)
  .replace('{num_of_rooms}', num_of_rooms)
  .replace('{num_of_adults}', num_of_adults)
  .replace('{check_in_date}', check_in_date)
  .replace('{check_out_date}', check_out_date);

const urlWithApiKey = `${formattedUrl}?api_key=${apiKey}`;

axios
  .get(urlWithApiKey)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.error(error);
  });

```

{% endtab %}
{% endtabs %}

### Response

The sample response of the API will look somewhat like this.

```json
{
                  "hotelName": "Hilton London Paddington",
                  "hotelId": "209371"
              },
              [
                  {
                      "price1": "279",
                      "tax1": "70",
                      "vendor1": "Prestigia.com"
                  },
                  {
                      "price2": "253",
                      "tax2": "51",
                      "vendor2": "eDreams"
                  },
                  {
                      "price3": "244",
                      "tax3": "48",
                      "vendor3": "Nustay.com"
                  },
                  {
                      "price4": null,
                      "tax4": null,
                      "vendor4": null
                  },
                  {
                      "price5": "253",
                      "tax5": "51",
                      "vendor5": "Tripadvisor"
                  }
              ]
          ],
          [
              {
                  "hotelName": "Park Grand London Hyde Park",
                  "hotelId": "3164384"
              },
              [
                  {
                      "price1": "263",
                      "tax1": "53",
                      "vendor1": "eDreams"
                  },
                  {
                      "price2": "263",
                      "tax2": "53",
                      "vendor2": "Booking.com"
                  },
                  {
                      "price3": "263",
                      "tax3": "53",
                      "vendor3": "Agoda.com"
                  },
                  {
                      "price4": null,
                      "tax4": null,
                      "vendor4": null
                  },
                  {
                      "price5": "263",
                      "tax5": "53",
                      "vendor5": "Tripadvisor"
                  }
              ]
          ],
          [
              {
                  "hotelName": "Park Plaza Westminster Bridge London",
                  "hotelId": "1657415"
              },
              [
                  {
                      "price1": "426",
                      "tax1": "85",
                      "vendor1": "eDreams"
                  },
                  {
                      "price2": "451",
                      "tax2": "113",
                      "vendor2": "Prestigia.com"
                  },
                  {
                      "price3": "415",
                      "tax3": "82",
                      "vendor3": "Nustay.com"
                  },
                  {
                      "price4": "455",
                      "tax4": "91",
                      "vendor4": "Agoda.com"
                  },
                  {
                      "price5": null,
                      "tax5": null,
                      "vendor5": null
                  }
              ]
          ],
          [
              {
                  "hotelName": "The Darlington Hyde Park",
                  "hotelId": "214639"
              },
              [
                  {
                      "price1": "252",
                      "tax1": "50",
                      "vendor1": "eDreams"
                  },
                  {
                      "price2": "252",
                      "tax2": "50",
                      "vendor2": "Booking.com"
                  },
                  {
                      "price3": "251",
                      "tax3": "50",
                      "vendor3": "Agoda.com"
                  },
                  {
                      "price4": null,
                      "tax4": null,
                      "vendor4": null
                  },
                  {
                      "price5": "252",
                      "tax5": "50",
                      "vendor5": "Tripadvisor"
                  }
              ]
  }
```

### Understand the Response

| Properties | Description                            |
| ---------- | -------------------------------------- |
| price      | Price offered by the vendor            |
| vendor     | Name of the vendor                     |
| tax        | Tax you will be charged at the booking |
| hotelName  | Name of the hotel                      |
| hotelId    | Id of the hotel in our system          |

{% hint style="info" %}
Each call in this pattern to our API will be counted as 1 API request. That means for every request to our API you will get 30 hotels in that target city.
{% endhint %}


# Hotel API - Search by hotel ID

This API can help you get more than 15 cheapest vendors per hotel. In this API you have to pass the hotel ID. We have our own hotel IDs which you have to map during integration.

The API endpoint for this API is: `https://api.makcorps.com/hotelsearch`

### Guide

This API does not require a JWT token because you need your own personal API key to access this API. You can [contact us](https://share.hsforms.com/1A-iwjye2SwWRv4VHhQbBqg439wf) if you need API keys to this API.&#x20;

Here is the list of default parameters you have to use with this API:

|                                                                         |                                                                         |
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| <p>hotel\_name<br><br><mark style="color:red;">required</mark></p>      | Name of the hotel. API will still work even if the name is not perfect. |
| <p>hotel\_id<br><br><mark style="color:red;">required</mark></p>        | This is the unique hotel ID provided by our system.                     |
| <p>num\_of\_adults<br><br><mark style="color:red;">required</mark></p>  | It is the number of adults.                                             |
| <p>num\_of\_rooms<br><br><mark style="color:red;">required</mark></p>   | It is the number of rooms.                                              |
| <p>check\_in\_date<br><br><mark style="color:red;">required</mark></p>  | <p>It is the check-in date.<br><br>Format - YYYY-MM-DD</p>              |
| <p>check\_out\_date<br><br><mark style="color:red;">required</mark></p> | <p>It is the check-out date.<br><br>Format - YYYY-MM-DD</p>             |

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET "https://api.makcorps.com/hotelsearch/{hotel_name}/{hotel_id}/{num_of_adults}/{num_of_rooms}/{check_in_date}/{check_out_date}?api_key=YOUR-API-KEY"
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = 'https://api.makcorps.com/hotelsearch/{hotel_name}/{hotel_id}/{num_of_adults}/{num_of_rooms}/{check_in_date}/{check_out_date}'
api_key = 'YOUR-API-KEY'

url = url.format(
    hotel_name='hotel-name',
    hotel_id='123',
    num_of_adults='2',
    num_of_rooms='1',
    check_in_date='2024-01-01',
    check_out_date='2024-01-02'
)

url_with_api_key = f"{url}?api_key={api_key}"

response = requests.get(url_with_api_key)

# Print the response
print(response.json())

```

{% endtab %}

{% tab title="Nodejs" %}

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

const url = 'https://api.makcorps.com/hotelsearch/{hotel_name}/{hotel_id}/{num_of_adults}/{num_of_rooms}/{check_in_date}/{check_out_date}';
const apiKey = 'YOUR-API-KEY';

const hotelName = 'hotel-name';
const hotelId = '123';
const numOfAdults = '2';
const numOfRooms = '1';
const checkInDate = '2024-01-01';
const checkOutDate = '2024-01-02';

const formattedUrl = url.replace('{hotel_name}', hotelName)
                        .replace('{hotel_id}', hotelId)
                        .replace('{num_of_adults}', numOfAdults)
                        .replace('{num_of_rooms}', numOfRooms)
                        .replace('{check_in_date}', checkInDate)
                        .replace('{check_out_date}', checkOutDate);

const urlWithApiKey = `${formattedUrl}?api_key=${apiKey}`;

axios.get(urlWithApiKey)
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error);
  });

```

{% endtab %}
{% endtabs %}

### Response

The sample response of the API will look somewhat like this.

```
{
  "comparison": [
    [
      {
        "vendor1": "Expedia.com",
        "price1": "$325",
        "tax1": "$53"
      },
      {
        "vendor2": "Booking.com",
        "price2": "$325",
        "tax2": "$53"
      },
      {
        "vendor3": "Tripadvisor",
        "price3": "$293",
        "tax3": "$48"
      },
      {
        "vendor4": "Hotels.com",
        "price4": "$325",
        "tax4": "$53"
      },
      {
        "vendor5": "Algotels",
        "price5": "$356",
        "tax5": "$90"
      },
      {
        "vendor6": "travelup.com",
        "price6": "$374",
        "tax6": "$88"
      },
      {
        "vendor7": "Orbitz.com",
        "price7": "$325",
        "tax7": "$53"
      },
      {
        "vendor8": "Agoda.com",
        "price8": "$325",
        "tax8": "$53"
      },
      {
        "vendor9": "Trip.com",
        "price9": "$325",
        "tax9": "$53"
      },
      {
        "vendor10": "Travelocity",
        "price10": "$325",
        "tax10": "$53"
      },
      {
        "vendor11": "ZenHotels.com",
        "price11": "$325",
        "tax11": "$74"
      },
      {
        "vendor12": "Vio.com",
        "price12": "$325",
        "tax12": "$53"
      },
      {
        "vendor13": "Priceline",
        "price13": "$325",
        "tax13": "$53"
      },
      {
        "vendor14": "Prestigia.com",
        "price14": "$325",
        "tax14": "$74"
      },
      {
        "vendor15": "StayForLong",
        "price15": "$326",
        "tax15": "$74"
      },
      {
        "vendor16": "Destinia.com",
        "price16": null,
        "tax16": null
      },
      {
        "vendor17": "Official Site",
        "price17": null,
        "tax17": null
      },
      {
        "vendor18": "Skyscanner.com",
        "price18": null,
        "tax18": null
      },
      {
        "vendor19": "SuperTravel",
        "price19": null,
        "tax19": null
      }
    ],
    [
      
    ]
  ]
}
```

### Understand the Response

|        |                                             |
| ------ | ------------------------------------------- |
| vendor | Name of the vendor                          |
| price  | Price offered by the vendor                 |
| tax    | Tax one has to pay while booking this hotel |

{% hint style="info" %}
This one single API call will be counted as 1 API request.
{% endhint %}