qsb.getLocations (

• callback: success_callback,
• callback: error_callback

)

This method fetches available unit cities and states/provinces from the API. Once it is fetched, the location data is cached in qsb.locations; subsequent calls will use this cache instead of re-fetching from the QSB API server.

success_callback will be passed the following object structure:

{
    "NC": [
        "Cary",
        "Raleigh",
        ...
    ],
    "VA": [
        "Lynchburg",
        "Richmond",
        ...
    ],
    ...
}
                    

Where the object has a property for each state or province code the host has units in, and each property is a list array of cities in that state where units are located.

This data is provided alphabetically sorted.

qsb.getAvailability (

• string: from,
• string: to,
• string/integer: num_guests,
• string: state,
• string: city,
• callback: success_callback,
• callback: error_callback

)

This call is basically the unit search. It gets unit availabilities for start/end dates "from" and "to", for the indicated number of guests. State and city may optionally be provided to narrow down the results further.

from and to should be strings containing dates formated either "month/day/year" or "year-month-day"; either format is understood. Four digit years should be used, however 0 padding the month and day are not required. "2023-4-9" and "9/4/2023" are acceptable date formats as an example.

num_guests should either be an integer or a string containing an integer. This is the number of guests in the party. QSB does not distinguish between children/infants and adult guests at this time.

state can either be a two-character state code as obtained from getLocations, or it can be an empty string to not filter by state.

city can be either a city string as obtained from getLocations, or it can be an empty string to not filter by city.

success_callback is optional, and if provided, will be run with the following data structure as its only parameter:

[
    {
        "id": "uuid based ID for unit",
        "title": "unit title",
        "description": "a brief description",
        "url": "a URL for more information",
        "max_guests": maximum number of guests,
        "num_bedrooms": integer number of bedrooms,
        "num_bathrooms": decimal number of bedrooms,
        "price": integer price in 'stripe' format
        "nights": number of nights,
        "price_per_night": price per night in 'stripe' format,
        "latitude": latitude geo location
        "longitude": longitude geo location,
        "type": This will be a text such as "House", "Apartment", etc.,
        "square_feet": size of unit in square feet
        "neighborhood": some brief text description about the location
        "bed_info": [
            {
                "King": integer,
                "Queen": integer,
                ...  (keys will be missing if 0)
            },
            ...
        ]
    },
    ...
]
                    

Some notes about this return structure:

• Most of these fields are set in the QSB unit editor. Title, description, url, max_guests, num_bedrooms, num_bathrooms, type, square_feet, neighborhood, and bed_info are directly powered by what is put in the unit editor.
• price is a price estimate and should not be presented as a final price; it doesn't include fees and taxes. This is the estimated total for the stay.
• nights is a count of the number of nights between the 'from' and 'to' dates, and is the total nights of the stay.
• price_per_night is a simple division of price by nights to get a nightly rate. It is just an estimate value as well, not factoring in taxes or fees.
• latitude and longitude are derived from the address you provide in the QSB unit editor. The resolution is intentionally low; if you use this to render a pin on a map, that pin will be somewhere within a couple miles of the house and not an exact location.

If invalid paramters are provided to the search, for example a date that does not exist or isn't properly formatted, you will get an error structure back instead:

{
    "error": true,
    "message": "a helpful message"
}
                    

If your user interface does not allow users to input invalid parameters -- for example, you use date pickers and don't allow arbitrary entry of random data -- you should never receive an error. However, if you do, please note that QSB will give a "200 OK" HTTP status but return the above error object.

As a final note, qsb.availability is set with the return value of getAvailability regardless of if success_callback is provided or not. This is not cached, so subsequenty calls to getAvailability will re-send the Ajax request.

error_callback is passed to jQuery.ajax directly and functions as noted in the Common Conventions section above.

qsb.getAvailability (

• string: from,
• string: to,
• string/integer: num_guests,
• string: query,
• string: center,
• callback: success_callback,
• callback: error_callback

)

This call is a twist on getAvailability. Similar to the first call, it gets unit availabilities for start/end dates "from" and "to", for the indicated number of guests. The difference is that we will use the HERE geocoding API to resolve 'query' and return results sorted by distance to the located point.

from and to should be strings containing dates formated either "month/day/year" or "year-month-day"; either format is understood. Four digit years should be used, however 0 padding the month and day are not required. "2023-4-9" and "9/4/2023" are acceptable date formats as an example.

num_guests should either be an integer or a string containing an integer. This is the number of guests in the party. QSB does not distinguish between children/infants and adult guests at this time.

query is a string; it can be anything, be it a point of interest or a specific address. It is very flexible and most queries will return some kind of search.

center is a latitude and longitude point in the string format "lat,lng" such as "35.9050059,-78.7749791". This 'centers' the search near that point, so that you are less likely to get results outside of the state or even country that your units are in.

success_callback is optional, and if provided, will be run with the following data structure as its only parameter:

{
    found: {
        // results from HERE API, documented here:
        https://www.here.com/docs/bundle/geocoding-and-search-api-developer-guide/page/topics-api/code-geocode-spatial-reference.html
    },
    results: [
        {
            "id": "uuid based ID for unit",
            "title": "unit title",
            "distance": distance in meters to location
            "description": "a brief description",
            "url": "a URL for more information",
            "max_guests": maximum number of guests,
            "num_bedrooms": integer number of bedrooms,
            "num_bathrooms": decimal number of bedrooms,
            "price": integer price in 'stripe' format
            "nights": number of nights,
            "price_per_night": price per night in 'stripe' format,
            "latitude": latitude geo location
            "longitude": longitude geo location,
            "type": This will be a text such as "House", "Apartment", etc.,
            "square_feet": size of unit in square feet
            "neighborhood": some brief text description about the location
            "bed_info": [
                {
                    "King": integer,
                    "Queen": integer,
                    ...  (keys will be missing if 0)
                },
                ...
            ]
        },
        ...
    ]
}
                    

Some notes about this return structure:

• Most of these fields are set in the QSB unit editor. Title, description, url, max_guests, num_bedrooms, num_bathrooms, type, square_feet, neighborhood, and bed_info are directly powered by what is put in the unit editor.
• price is a price estimate and should not be presented as a final price; it doesn't include fees and taxes. This is the estimated total for the stay.
• nights is a count of the number of nights between the 'from' and 'to' dates, and is the total nights of the stay.
• price_per_night is a simple division of price by nights to get a nightly rate. It is just an estimate value as well, not factoring in taxes or fees.
• latitude and longitude are derived from the address you provide in the QSB unit editor. The resolution is intentionally low; if you use this to render a pin on a map, that pin will be somewhere within a couple miles of the house and not an exact location.

If invalid paramters are provided to the search, for example a date that does not exist or isn't properly formatted, you will get an error structure back instead:

{
    "error": true,
    "message": "a helpful message"
}
                    

If your user interface does not allow users to input invalid parameters -- for example, you use date pickers and don't allow arbitrary entry of random data -- you should never receive an error. However, if you do, please note that QSB will give a "200 OK" HTTP status but return the above error object.

As a final note, qsb.availability is set with the return value of getAvailability regardless of if success_callback is provided or not. This is not cached, so subsequenty calls to getAvailability will re-send the Ajax request.

error_callback is passed to jQuery.ajax directly and functions as noted in the Common Conventions section above.

qsb.validateUser (

• string: email,
• string/integer: code,
• callback: success_callback,
• callback: error_callback

)

loginUser will send the user an email with a 6 digit code in it. This call takes the user's email address and that 6 digit code, and validates them.

email is the email that the code was sent to; it should be the same as what was passed to loginUser

code is either an integer or a string containing an integer with the six digit code.

success_callback will be passed a single parameter with the following object:

{
    "message": "some message",
    "success": true if success, false if failed, message has error
    "stripe_customer": stripe customer ID string (if success)
}
                    

'message' is usually irrelevant if this call is successful, but it will have an error message if something went wrong (such as an invalid code).

'stripe_customer' is their Stripe customer_id and is safe to reveal, unencrypted, to the user. You may store this in a cookie or some session variable if you wish, but that is not required.

'stripe_customer' is needed to book the unit, using bookUnit

'message' is safe to display to the user, and showing them the message is recommended as the error may be informative. This call will always return 200 unless you provided an incorrect QuantumSuites API key.

error_callback is passed to jQuery.ajax directly and functions as noted in the Common Conventions section above.

qsb.getNextAvailability (

• string/integer: nights,
• string/integer: num_guests,
• string: state,
• string: city,
• callback: success_callback,
• callback: error_callback

)

This call is used to fetch available units based on a number of days rather than specific dates. Specifically, it returns the next availabilities of all your units for a stay of 'nights' number of nights.

nights is the number of nights of availability required as an integer or string containing integer.

num_guests is the number of guests staying as an integer or string containing integer.

state contains a 2 letter state or province code as returned from getLocations. It is optional, if left off, all states will be queried.

city contains a city from getLocations. It is optional, if left off, all cities will be queried.

success_callback will be called on completion and, for this call, is required as you won't get any data from this if ignored. The structure passed to the callback will be:

[
    {
        "id": "uuid based ID for unit",
        "title": "unit title",
        "url": "a URL for more information",
        "neighborhood": some brief text description about the location,
        "nights_available": Number of nights available
        "starting": date the nights_available starts,
        "city": city,
        "province": province
        "num_bedrooms": number of bedrooms,
        "num_bathrooms": number of bathrooms
    },
    ...
]

If invalid paramters are passed, you can receive an error object. You should validate the user's input rather than allow this to happen.

{
    "error": true,
    "message": a helpful message but maybe not the best for the user
}

This call will always return a 200 status code unless provided an invalid API key.

error_callback is passed to jQuery.ajax directly and functions as noted in the Common Conventions section above.

qsb.unitFromUrl (

• string: url,
• callback: success_callback,
• callback: error_callback

)

Unit URLs are used to glue your site and Quantum Suites together seamlessly. For more details about our recommendations here, see the section above.

The url parameter should be the end portion of a URL. For instance, if your unit detail page has the url:

http://yoursite.com/units/detail/1234.html

You could pass '1234.html' to the url parameter and receive the QSB unit ID assuming the unit URL is configured correctly in the QSB back-end.

success_callback will receive the following structure:

[
    {
         "id": the unit ID
         "url": the URL we have on record
         "title": the title we have for the unit
    },
    ...
]

Note that it is technically possible to match multiple URLs in the case that what you pass isn't sufficiently distinct. Thus, this returns a list with all matches. Of course, you may also match nothing and receive an empty list. This call will never generate an error.

error_callback is passed to jQuery.ajax directly and functions as noted in the Common Conventions section above.

$qsb->getLocations ()

This method fetches available unit cities and states/provinces from the API. We recommend caching the return value of this as it will rarely change. The return value will be a PHP dictionary array such as:

{
    "NC": [
        "Cary",
        "Raleigh",
        ...
    ],
    "VA": [
        "Lynchburg",
        "Richmond",
        ...
    ],
    ...
}
                    

Where the object has a property for each state or province code the host has units in, and each property is a list array of cities in that state where units are located.

This data is provided alphabetically sorted.

qsb.getAvailability (

• string: from,
• string: to,
• string/integer: num_guests,
• string: query,
• string: center

)

This call is a twist on getAvailability. Similar to the first call, it gets unit availabilities for start/end dates "from" and "to", for the indicated number of guests. The difference is that we will use the HERE geocoding API to resolve 'query' and return results sorted by distance to the located point.

from and to should be strings containing dates formated either "month/day/year" or "year-month-day"; either format is understood. Four digit years should be used, however 0 padding the month and day are not required. "2023-4-9" and "9/4/2023" are acceptable date formats as an example.

num_guests should either be an integer or a string containing an integer. This is the number of guests in the party. QSB does not distinguish between children/infants and adult guests at this time.

query is a string; it can be anything, be it a point of interest or a specific address. It is very flexible and most queries will return some kind of search.

center is a latitude and longitude point in the string format "lat,lng" such as "35.9050059,-78.7749791". This 'centers' the search near that point, so that you are less likely to get results outside of the state or even country that your units are in.

A PHP associative array is returned:

{
    found: {
        // results from HERE API, documented here:
        https://www.here.com/docs/bundle/geocoding-and-search-api-developer-guide/page/topics-api/code-geocode-spatial-reference.html
    },
    results: [
        {
            "id": "uuid based ID for unit",
            "title": "unit title",
            "distance": distance in meters to location
            "description": "a brief description",
            "url": "a URL for more information",
            "max_guests": maximum number of guests,
            "num_bedrooms": integer number of bedrooms,
            "num_bathrooms": decimal number of bedrooms,
            "price": integer price in 'stripe' format
            "nights": number of nights,
            "price_per_night": price per night in 'stripe' format,
            "latitude": latitude geo location
            "longitude": longitude geo location,
            "type": This will be a text such as "House", "Apartment", etc.,
            "square_feet": size of unit in square feet
            "neighborhood": some brief text description about the location
            "bed_info": [
                {
                    "King": integer,
                    "Queen": integer,
                    ...  (keys will be missing if 0)
                },
                ...
            ]
        },
        ...
    ]
}
                    

Some notes about this return structure:

• Most of these fields are set in the QSB unit editor. Title, description, url, max_guests, num_bedrooms, num_bathrooms, type, square_feet, neighborhood, and bed_info are directly powered by what is put in the unit editor.
• price is a price estimate and should not be presented as a final price; it doesn't include fees and taxes. This is the estimated total for the stay.
• nights is a count of the number of nights between the 'from' and 'to' dates, and is the total nights of the stay.
• price_per_night is a simple division of price by nights to get a nightly rate. It is just an estimate value as well, not factoring in taxes or fees.
• latitude and longitude are derived from the address you provide in the QSB unit editor. The resolution is intentionally low; if you use this to render a pin on a map, that pin will be somewhere within a couple miles of the house and not an exact location.

If invalid paramters are provided to the search, for example a date that does not exist or isn't properly formatted, you will get an error structure back instead:

{
    "error": true,
    "message": "a helpful message"
}
                    

If your user interface does not allow users to input invalid parameters -- for example, you use date pickers and don't allow arbitrary entry of random data -- you should never receive an error. However, if you do, please note that QSB will give a "200 OK" HTTP status but return the above error object.

$qsb->loginUser(

• string: email
• string: unit_host_id

)

In order for a user to book a unit, they have to be "logged in". This call will cause QSB to send an email to the email address provided. That email will contain a code which you will in turn pass to validateUser to validate them and confirm the login.

email is the address where we will send their code. This is rate-limited so it cannot be used for SPAM.

unit_host_id is the unit we're booking's host ID. This comes from getPricing, or if all the units on your site belong to the same user, you can just hard-code it to your Quantum Suites API user.

You will receive the following associative array as a return:

{
    "message": "some message",
    "success": true if success, false if failed, message has error
}
                    

'message' is safe to display to the user, and showing them the message is recommended as the error may be informative. This call will always return 200 unless you provided an incorrect QuantumSuites API key.

$qsb->bookUnit(

• string: unit_id,
• string: from,
• string: to,
• string/integer: num_guests,
• string/integer: dogs,
• string/integer: cats,
• string: customer_id,
• string: city,
• string: state

)

This call actually creates a reservation in the system. However, the reservation isn't confirmed until payment is completed.

When you call this, you will receive a Stripe "client_secret" that can be used to present a Stripe payment form. We provide examples of this in the examples section.

unit_id is a UUID-format string as received from getAvailabilities or unitFromUrl.

from and to are strings containing dates in the format described by getAvailabilities.

num_guests is either an integer or string containing integer number of guests staying at the property.

dogs is either an integer or string containing integer number of dogs staying at the property. This may be blank or 0.

cats is either an integer or string containing integer number of cats or other non-dog animals requiring a special deposit staying at the property. This may be blank or 0.

customer_id is the value obtained from validateUser.

city and state should be the unit's city and state as obtained from getAvailabilities. In a pinch, these can be blank strings; the purpose of passing these is to automatically query for alternative units if the unit was booked out from under the customer during the checkout process.

This call will return the following as an associative array:

{
    'available' => true,
    'client_secret' => Stripe client secret for payment intent
    'expires' => expiration UNIX timestamp, in seconds
    'contract_url' => URL to send the customer to sign contract
                      AFTER payment is done.  Use this as the
                      stripe return URL.
}
                    

If the unit was booked while the customer was going through the checkout process, you will instead receive:

{
    "available": false,
    "alternatives": [
        // same structure as 'getAvailability'
    ]
}
                    

In case of an error, which would be if, for instance, the dates are invalid, you will receive this instead. If your form is properly validating user input, this should never happen.

{
    "error": true,
    "message": "a helpful message"
}
                    

This call will always return a 200 status code unless provided an invalid API key.

$qsb->getPricing(

• string: unit_id,
• string: from,
• string: to,
• string/integer: num_guests,
• string/integer: num_dogs,
• string/integer: num_cats,
• string: city,
• string: state,
• string: customer_id

)

This call produces a full final price for a unit, completely broken down with taxes and fees. It is designed to be called when displaying the checkout screen.

unit_id is a UUID-format string as received from getAvailabilities or unitFromUrl.

from and to are strings containing dates in the format described by getAvailabilities.

num_guests is either an integer or string containing integer number of guests staying at the property.

dogs is either an integer or string containing integer number of dogs staying at the property. This may be blank or 0.

cats is either an integer or string containing integer number of cats or other non-dog animals requiring a special deposit staying at the property. This may be blank or 0.

city and state should be the unit's city and state as obtained from getAvailabilities. In a pinch, these can be blank strings; the purpose of passing these is to automatically query for alternative units if the unit was booked out from under the customer during the checkout process.

customer_id is the value obtained from validateUser. It is optional and may be an empty string or false if you don't have it. The reasoning for passing it here is so that, if a customer has a booking in progress, that booking won't count against availability if the getPricing is called during the checkout process.

You will receive the following associative array as a return:

{
    "available": true,
    "num_nights": integer number of nights in the stay,
    "pay_schedule": [
        {
            "charge_on": "YYYY-MM-DD",
            "amount": integer in stripe format
            "amount_tax": integer in stripe format
        },
        ...
    ],
    "totals": {
        "num_nights": integer number of nights of the stay
        "cat_deposit": integer amount in 'stripe' format
        "pet_fee": integer amount in 'stripe' format
        "authorize": integer amount in 'stripe' format
        "charge": integer amount in 'stripe' format
        "charge_tax": integer amount in 'stripe' format
        "monthly": integer amount in 'stripe' format
        "monthly_tax": integer amount in 'stripe' format
        "last_month": integer amount in 'stripe' format
        "last_month_tax": integer amount in 'stripe' format
        "total_cost": integer amount in 'stripe' format
        "total_tax": integer amount in 'stripe' format
        "utility_fee": integer amount in 'stripe' format
    },
    "title": "unit title",
    "description": "a brief description",
    "url": "a URL for more information",
    "price_per_night": price per night in 'stripe' format,
    "neighborhood": some brief text description about the location
    "unit_host_id": the host ID of the unit owner, used by login
    "stripe_publish_key": the stripe key to use to book the unit
}

Note about "pay_schedule"; this is a list of payments that will be made in the future, if the user has booked a reservation longer than 28 days and will thus be paying some kind of periodic rent instead of paying for the entire reservation up front.

Therefore, for reservations 28 days or shorter, this will be an empty list.

If the unit is not available because someone booked it before this call was made, you will receive:

{
    "available": false,
    "next_available": {  Next time the unit requested is available
        "available_start": "YYYY-MM-DD" date unit is available
        "available_checkout": "YYYY-MM-DD" proposed checkout date
        "available_nights": integer night count, or null if calendar is open.
        "title": "unit title",
        "description": "a brief description",
        "url": "a URL for more information",
        "neighborhood": some brief text description about the location,
        "max_guests": maximum number of guests,
        "num_bedrooms": integer number of bedrooms,
        "num_bathrooms": decimal number of bedrooms,
        "latitude": latitude geo location
        "longitude": longitude geo location,
        "type": This will be a text such as "House", "Apartment", etc.,
        "square_feet": size of unit in square feet
        "price": integer price in 'stripe' format
        "nights": number of nights,
        "price_per_night": price per night in 'stripe' format,
        "bed_info": [
            {
                "King": integer,
                "Queen": integer,
                ...  (keys will be missing if 0)
            },
            ...
        ]
    },
    "alternatives": [
        // same structure as 'getAvailability'
    ]
}

next_available is details about the next time the unit will be available, and 'alternatives' returns a list similar to getAvailability of other units that are available for the same dates and number of guests.

The following structure will be returned if invalid inputs are provided (i.e. incorrect dates). Ideally, you should validate user input to prevent this:

{
    "error": true,
    "message": a helpful message but maybe not the best for the user
}

This call will always return a 200 status code unless provided an invalid API key.

$qsb->blockedDates(

• string: unit_id

)

Sometimes it is desirable to know which dates are already booked; for instance, when presenting a calendar widget for a unit, you may wish to have dates that are not available to be already blocked.

This call will return a list with start/end date pairs for a provided unit_id. You will receive the following array as a return:

[
  [start_date, end_date],
  [start_date, end_date],
  ...
]

This may be an empty list if the unit has no blocks on the calendar. It will never return an error assuming unit_id is valid (if it is not valid, you will receive a 404 error).