Q4VR HUB API Documentation / Testing Examples

Testing Q4HUB API Calls

Testing the Q4HUB response data will help you determine if your error is in the Hub or the VR plugin. If you get your expected response, you know it’s a plugin issue. The Q4HUB is making API calls to the PMS based on the Vacation Rental Service entered on a customer’s hub account. The hub also passes the username/password information from this section to get the correct info back. The Q4HUB has Controllers that handle the calls to the PMS APIs.

To test the Q4HUB, we can use Postman (https://www.postman.com/downloads/). This will allow us to make an API call using the same key used in the Q4VR Plugin for the customer. These keys are created in the customer’s Q4HUB account under API.

In the below examples, you will see me using different hub urls. When you do your Postman call you need the HUB api key found in the customer’s VR settings in WordPress.

For the HUB address use:

  • https://q4-hub.com This is the live hub.

The result you get in Postman is the same JSON data that is getting passed to the VR Plugin. The Postman result does NOT show you all of the information that is getting passed to the HUB from the PMS.

In the following pages, you can see how to make API calls to see all of a customer’s units, see the details of one specific unit, and get the booking information for a specific unit during a specified date range.

GET ALL UNITS

Request

To get the list of units, open Postman and use the following Settings:

                        KEY                    VALUE

    • Content-Type           application/json
    • Accept                      application/json
    • Authorization          Bearer <API KEY HERE>
  • Click Send (array of units should populate Response Area)

If you look at the very bottom of the response (or use the little arrow next to Row 2 in the response to close the units array), you can see the total number of units returned. This is helpful if the customer is saying they should show X number of units in their All Properties page. You can check the API return to see if there is an issue with the HUB accessing a unit or if you just need to resync the plugin to pull in a new unit.

Response

Sample Response data from a GetUnits request for an Escapia Customer. The actual return had 31 units, but this is a sample of the data:
Request: https://q4-hub.com/api/vacation-rentals/units/

{
    "units": [
        {
            "unit_code": "1907-90546",
            "name": "Adagio C403",
            "address": {
                "address_line1": "2421 W County Hwy 30A",
                "address_line2": "Unit C403",
                "city": "Santa Rosa Beach",
                "state": "FL",
                "zip": "32459",
                "country": "US"
            },
            "default_image_url": "https://pictures.escapia.com/FRNDBE/7935900099.jpg",
            "rooms": [
                {
                    "type": "Bedrooms",
                    "count": 4
                },
                {
                    "type": "Bathrooms",
                    "count": 3
                }
            ],
            "max_occupancy": 10,
            "rates": [
                {
                    "base_rate": "$366-$996",
                    "min_rent": "$275",
                    "max_rent": "$842",
                    "min_rate": "$366",
                    "max_rate": "$996"
                }
            ]
        },
          {
            "unit_code": "1907-98769",
            "name": "Adagio A102",
            "address": {
                "address_line1": "2421 W County Hwy 30A",
                "address_line2": "Unit A102",
                "city": "Santa Rosa Beach",
                "state": "FL",
                "zip": "32459",
                "country": "US"
            },
            "default_image_url": "https://pictures.escapia.com/FRNDBE/2353050410.jpg",
            "rooms": [
                {
                    "type": "Bedrooms",
                    "count": 4
                },
                {
                    "type": "Bathrooms",
                    "count": 3
                }
            ],
            "max_occupancy": 10,
            "rates": [
                {
                    "base_rate": "$366-$1012",
                    "min_rent": "$275",
                    "max_rent": "$857",
                    "min_rate": "$366",
                    "max_rate": "$1012"
                }
            ]
        },
     ],

    "summary": {

        "returned": 2,

        "total": 2

    }

}

SEARCH UNITS

Request

To return only units that fit search parameters. Set up like GET UNITS, but add parameters to filter units.

  • Parameters:
    • start_date, unit_name, end_date, guests, areas, locations, min_bedrooms, max_bedrooms, min_bathrooms, property_type, filter, amenities, page, unit_code, unit_codes

Response

The response for a unit search will look the same as the response for all units. See above for example.

GET INDIVIDUAL UNIT

Request

If you request data on an individual unit, you can see additional details. In this case, use the same settings EXCEPT, change your URL to include the “unit_code” for the unit you want like so:

  • URL: https://q4hub.com/api/vacation-rentals/units/<unit_code>
    • example: https://q4hub.com/api/vacation-rentals/units/1464-49970

I will often do a search for all of the units, and then copy a unit code from that list. If your customer puts spaces in their unit codes, the code you find in Escapia or V12 will differ from the unit code you need to use in your URL – the hub will add %20 in place of spaces to make the URL work.

If you look at the bottom of the response, you can see the metadata the VR Plugin is using for its filters.

Response

Sample response for Escapia Unit. Response edited for length (removed extra items in arrays), but you can see an example of each part. These can vary slightly by PMS because the data is returned differently for each one.

Request: https://q4-hub.com/api/vacation-rentals/units/1856-101526/

{
    "unit_code": "1856-101526",
    "name": "Modern Love",
    "headline": "Charming Mid-Century!  Oceanview, 1 Block to Beach, Zen and Retro in one!",
    "description": "Starfish Vacation Rentals is pleased to offer Modern Love, a fabulous mid-century, light-filled home just a block from the ocean. Arch Cape is a peaceful beach, perfect for those who wish to escape to a laid back place by the sea - you and your family will enjoy exploring the tide pools, caves, streams, rock arch, and waterfall that dot the shoreline.\n\nModern Love offers everything a family or two couples need for a luxurious and memorable vacation at the beautiful Oregon Coast. A short, easy walk to the beach and located just minutes outside of both Manzanita and Cannon Beach, this modern escape is close to shops and restaurants.Come experience the 5-star hospitality and concierge services offered by Starfish Vacation Rentals - we know you'll love it!",
    "default_image_url": "https://pictures.escapia.com/STRFSH/101526/1864520570.jpg",
    "rooms": [
        {
            "type": "Bedrooms",
            "count": "2"
        },
        {
            "type": "Bathrooms",
            "count": "2"
        },
        {
            "type": "Garages",
            "count": "2"
        }
    ],
    "beds": null,
    "address": {
        "address_line1": "80147 Kent Rd.",
        "address_line2": null,
        "city": "Arch Cape",
        "state": "OR",
        "zip": "97102",
        "country": "US"
    },
    "amenities": [
        {
            "name": "Name",
            "value": "Combination tub/shower",
            "category": "Amenity",
            "class": "CombinationTub/shower"
        },
        {
            "name": "Name",
            "value": "Ocean View",
            "category": "Location Type",
            "class": "OceanView"
        },
        {
            "name": "Name",
            "value": "Deck / Patio",
            "category": "Outside",
            "class": "Deck/Patio"
        },
        {
            "name": "Name",
            "value": "Pets not allowed",
            "category": "Suitability",
            "class": "PetsNotAllowed"
        }
    ],
    "max_occupancy": 4,
    "pet_policy": false,
    "position": {
        "lat": "45.813066",
        "lon": "-123.961841",
        "show": true
    },
    "media": {
        "images": [
            {
                "url": "https://pictures.escapia.com/STRFSH/101526/1864520570.jpg",
                "filename": "1864520570.jpg",
                "caption": "Cozy light-filled main living area"
            },
            {
                "url": "https://pictures.escapia.com/STRFSH/101526/8303010612.jpg",
                "filename": "8303010612.jpg",
                "caption": "Modern Love"
            }
        ],
        "videos": [
            {
                "url": "https://tour.TruPlace.com/property/1292/56776/"
            }
        ]
    },
    "policies": null,
    "reviews": {
        "0": {
            "title": "Arch Cape Getaway",
            "name": "Tom T.",
            "date": "Nov 2018",
            "body": "Had a great time at the Modern Love rental. Starfish Vacation Rentals were very professional to work with.The Arch Cape area was just what were were looking for. The house had everything we needed for a 3 night stay. The only issue would be the highway traffic noise at night. We would come back.",
            "rating": 5,
            "display": true,
            "response": null
        },
        "1": {
            "title": "Serene Beach Retreat",
            "name": "Jenise A.",
            "date": "Oct 2018",
            "body": "A well kept and superbly appointed beach house that was both inviting and comfortable from the Livng space to the Kitchen and continuing into the Master Bedroom and Bathroom. There wasn't one amenity or needed item that wasn't provided and done so in a fairly high quality way.",
            "rating": 5,
            "display": true,
            "response": "Thank you for taking the time to write a review of your stay at Modern Love.  We're so glad you found the home perfect for your needs - we couldn't agree more with your description about the home being rustic with a touch of sophistication.  All the ingredients for a luxurious stay without being stuffy. We at Starfish Vacation Rentals want our guests to know we're available for any needs that should come up, and we're glad to hear our communication struck the right chord.  We hope to welcome you back again soon."
        } 
    }
    "review_overview": {
        "AverageReviewScore": 4.84707903780068694032934217830188572406768798828125,
        "ReviewCount": 1164
    },
    "minimumNights": null,
    "rates": [
        {
            "base_rate": "$100-$128",
            "base_rate_plus_fees": "$148-$228",
            "start_date": "2019-01-21",
            "end_date": "2019-02-13",
            "nights": 2,
            "type": "Nightly",
            "checkin": [
                "Monday",
                "Tuesday",
                "Wednesday",
                "Thursday",
                "Friday",
                "Saturday",
                "Sunday"
            ],
            "checkout": [
                "Monday",
                "Tuesday",
                "Wednesday",
                "Thursday",
                "Friday",
                "Saturday",
                "Sunday"
            ],
            "context": "Checkin"
        },
        {
            "base_rate": "$187",
            "base_rate_plus_fees": "$270",
            "start_date": "2019-02-14",
            "end_date": "2019-02-17",
            "nights": 3,
            "type": "Nightly",
            "checkin": [
                "Thursday",
                "Friday",
                "Saturday",
                "Sunday"
            ],
            "checkout": [
                "Monday",
                "Tuesday",
                "Wednesday",
                "Thursday",
                "Friday",
                "Saturday",
                "Sunday"
            ],
            "context": "Checkin"
        },
        {
            "base_rate": "$100-$181",
            "base_rate_plus_fees": "$143-$290",
            "start_date": "2019-02-18",
            "end_date": "2019-03-21",
            "nights": 2,
            "type": "Nightly",
            "checkin": [
                "Monday",
                "Tuesday",
                "Wednesday",
                "Thursday",
                "Friday",
                "Saturday",
                "Sunday"
            ],
            "checkout": [
                "Monday",
                "Tuesday",
                "Wednesday",
                "Thursday",
                "Friday",
                "Saturday",
                "Sunday"
            ],
            "context": "Checkin"
        },
    ],
    "ratesTable": [
        {
            "season": "Winter",
            "start_date": "1/21/2019",
            "end_date": "2/13/2019",
            "nights": 2,
            "daily": "$100",
            "weekly": "$754",
            "monthly": null
        },
        {
            "season": "Presidents' weekend",
            "start_date": "2/14/2019",
            "end_date": "2/17/2019",
            "nights": 3,
            "daily": "$187",
            "weekly": null,
            "monthly": null
        },
        {
            "season": "Winter",
            "start_date": "2/18/2019",
            "end_date": "3/21/2019",
            "nights": 2,
            "daily": "$100",
            "weekly": "$894",
            "monthly": "$4005"
        },
        {
            "season": "Spring Break*",
            "start_date": "3/22/2019",
            "end_date": "4/6/2019",
            "nights": 3,
            "daily": "$128",
            "weekly": "$1263",
            "monthly": null
        },
    ],
    "meta_data": {
        "Property Type": "Cottage",
        "Area": "Arch Cape",
        "Custom1": "The Haus",
        "Custom2": "shorebird",
        "DiningSeats": "4",
        "DisplayRate": "100-275",
        "LocationField": "Starfish Vacation Rentals",
        "View": "Oceanview"
    }
}

GET UNIT STAY

Request

Getting the unit stay will show you the data used to provide a quote and fill in the data on the booking page. For this API call, your Request Type and Headers will be the same, but you need to add extra parameters to the URL. To do this type of test, you will need:

                  KEY             VALUE

    • guests: <number value>
    • coupon_code: <valid code>

(Postman will add your parameters to your URL by putting a “?” after your end date, and then listing the parameters as “key=value” linked together with “&”. A full example URL with multiple parameters is: https://q4hub.com/api/vacation-rentals/units/BV%20Q%20hotel%201123/stay/2017-12-04/2017-12-07?guests=2&coupon_code=SUN50 )

Response

Response will vary slightly based on PMS. Only Escapia returns Terms & Conditions and Cancellation Policy – that data must be entered in the Q4VR Plugin Settings under the preferences tab for other PMSs.

Request: https://q4-hub.com/api/vacation-rentals/units/54345/stay/2019-08-12/2019-08-17

{
    "rates": {
        "base": 1275,
        "taxes": [
            {
                "id": 32683,
                "name": "County Tax",
                "value": 147.5,
                "description": "County Tax",
                "damage_waiver": 0,
                "travel_insurance": 0,
                "cfar": 0
            },
            {
                "description": "County Tax",
                "amount": 147.5
            }
        ],
        "fees": [
            {
                "description": "Cleaning Fee",
                "category": "Cleaning Fee",
                "amount": 200,
                "type": "Cleaning Fee",
                "tax_inclusive": "",
                "mandatory": true
            },
            {
                "description": "Rental Guardian Damage Waiver (1500)",
                "category": "Rental Guardian Damage Waiver (1500)",
                "amount": 59,
                "type": "Rental Guardian Damage Waiver (1500)",
                "tax_inclusive": "",
                "mandatory": true
            }
        ],
        "additional_charges": [
            {
                "description": "Rental Guardian Trip Insurance",
                "category": "Rental Guardian Trip Insurance Charge",
                "amount": 113.5799999999999982946974341757595539093017578125,
                "taxes": 0,
                "charge_template_id": 32038,
                "checked": ""
            },
            {
                "description": "TripHedge Cancel For Any Reason",
                "category": "TripHedge Cancel For Any Reason Charge",
                "amount": 159.009999999999990905052982270717620849609375,
                "taxes": 0,
                "charge_template_id": 41616,
                "checked": ""
            }
        ],
        "leaseid": ""
    },
    "guests": [
        2,
        0,
        0
    ],
    "time_span": {
        "start_date": "2019-08-12",
        "end_date": "2019-08-17"
    },
    "installments": null,
    "rental_agreement": null,
    "cancellation_policy": null,
    "totals": {
        "taxes": 147.5,
        "amount_before_tax": 1534,
        "total": 1681.5
    },
    "acceptedPayments": [
        "VI",
        "MC",
        "DS",
        "AX"
    ],
    "unit": {GetUnit data here}
}

 

GET UNIT CALENDAR

Request

Getting the unit calendar will show you the data used to fill the calendar data in the Availability and Datepicker calendars on the unit page. For this API call, your Request Type and Headers will be the same. To do this type of test, you will need:

  • URL: https://q4-hub.com/api/vacation-rentals/units/<unit-code>/calendar/<startdate>/<enddate>
    • Date Format: yyyy-mm-dd
    • Usually use start date as today, and end date as 1 year from today, but you can adjust depending on what you need to know

Response

Request (Escapia): https://q4-hub.com/api/vacation-rentals/units/1856-101526/calendar/2019-01-28/2019-02-28

Responses will vary based on PMS because the way the rates, checkin/checkout rules, minimum night requirements, and availability are returned differs between the PMSs.

{
    "checkin_unavailable": [
        "2019-01-28",
        "2019-02-15",
        "2019-02-21",
    ],
    "checkout_unavailable": [
        "2019-02-06",
        "2019-02-18",
        "2019-02-24",
    ],
    "unavailable": [
        "2019-01-29",
        "2019-01-30",
        "2019-01-31",
        "2019-02-01",
        "2019-02-02",
        "2019-02-03",
        "2019-02-04",
        "2019-02-05",
        "2019-02-16",
        "2019-02-17",
        "2019-02-22",
        "2019-02-23",
    ],
    "minimumNights": [
        {
            "base_rate": "$100-$144",
            "base_rate_plus_fees": "$153-$247",
            "start_date": "2019-01-21",
            "end_date": "2019-02-13",
            "nights": 2,
            "type": "Nightly",
            "checkin": [
                "Monday",
                "Tuesday",
                "Wednesday",
                "Thursday",
                "Friday",
                "Saturday",
                "Sunday"
            ],
            "checkout": [
                "Monday",
                "Tuesday",
                "Wednesday",
                "Thursday",
                "Friday",
                "Saturday",
                "Sunday"
            ],
            "context": "Checkin"
        },
        {
            "base_rate": "$230",
            "base_rate_plus_fees": "$319",
            "start_date": "2019-02-14",
            "end_date": "2019-02-17",
            "nights": 3,
            "type": "Nightly",
            "checkin": [
                "Thursday",
                "Friday",
                "Saturday",
                "Sunday"
            ],
            "checkout": [
                "Monday",
                "Tuesday",
                "Wednesday",
                "Thursday",
                "Friday",
                "Saturday",
                "Sunday"
            ],
            "context": "Checkin"
        },
     ],
    "calendar_minLOS": {
        "2019-01-28": 2,
        "2019-01-29": 2,
        "2019-01-30": 2,
        "2019-01-31": 2,
        "2019-02-13": 3,
        "2019-02-14": 3,
        "2019-02-15": 3,
    },
    "latestAvailableDate": "2019-11-23"
}

GET UNIT AVAILABILITY (Beyond Pricing)

Request

If your customer has Beyond Pricing set up, the Availability Calendar will use this API call to get availability and rates from Beyond Pricing. The DatePicker will still use GetCalendar. For this API call, your Request Type and Headers will be the same. To do this type of test, you will need:

  • URL: https://q4-hub.com/api/vacation-rentals/units/<bp-code>/availability/<startdate>/<enddate>
    • BP-code: The beyond pricing ID for the unit. Saved in metadata when synced if beyond pricing is turned on.
    • Date Format: yyyy-mm-dd (Just present in case the HUB needs to revert to GetCalendar. Beyond Pricing will return all dates with rates.
    • Usually use start date as today, and end date as 1 year from today, but you can adjust depending on what you need to know

Response

Request: https://q4-hub.com/api/vacation-rentals/units/316864/availability/2019-01-28/2020-01-10

Notice the Beyond Pricing return does not have information about checkin/checkout rules or minimum nights. The minimumNights array is in the return, but in the plugin, the prices are actually pulled from the “bpRates” array because it’s faster than looping through the minimumNightsArray.

{
    "checkin_unavailable": [
        "2019-02-04",
        "2019-03-27",
    ],
    "checkout_unavailable": [
        "2019-02-03",
        "2019-03-05",
    ],
    "unavailable": [
        "2019-01-29",
        "2019-01-30",
        "2019-01-31",
        "2019-02-01",
        "2019-02-02",
        "2019-02-05",
        "2019-02-06",
        "2019-02-07",
        "2019-02-08",
        "2019-02-09",
    ],
    "minimumNights": [
        {
            "base_rate": "$340",
            "start_date": "2019-01-28",
            "end_date": "2019-01-28",
            "type": "beyond_pricing"
        },
        {
            "base_rate": "$340",
            "start_date": "2019-01-29",
            "end_date": "2019-01-29",
            "type": "beyond_pricing"
        },
        {
            "base_rate": "$340",
            "start_date": "2019-01-30",
            "end_date": "2019-01-30",
            "type": "beyond_pricing"
        },
],
"bpRates": {
        "2019-01-28": "$340",
        "2019-01-29": "$340",
        "2019-01-30": "$340",
        "2019-01-31": "$340",
 },
 "latestAvailableDate": "2020-03-22"
}

GET BEYOND PRICING LISTINGS

Request

If your customer has Beyond Pricing set up, the plugin will use this method during SYNC to save the Beyond Pricing listing IDs in the metadata of the associated vacation rental post. Then, when your Availability calendar uses the GetAvailability method, it will inject this listing ID in the place of the unit ID. For this API call, your Request Type and Headers will be the same. To do this type of test, you will need:

Response

Request: http://q4-hub.com/api/vacation-rentals/units/beyond-pricing-listings

{
    "listings": [
        {
            "id": 275430,
            "name": "HK 103 - Hale Kamaole 103",
            "address": "2737 South Kihei Rd."
        },
        {
            "id": 275371,
            "name": "KS 2-105 - Kamaole Sands 2-105",
            "address": "2695 South Kihei Rd."
        },
}

CHECK API CONNECTION (PING)

Request

If you just want to make sure your API connection is working, you can use this request. It will return the services your customer subscribes to in the HUB, which should include “vr”.  For this API call, your Request Type and Headers will be the same. To do this type of test, you will need:

Response

{
    "services": [
        "vr",
        "og"
    ]
}

Leave a Reply