Skip to content

Poplidays

Jump to bottom
Konstantin Kolotyuk edited this page Aug 10, 2016 · 15 revisions

Poplidays is a French supplier with properties over Europe. At the time of this writing, the majority of the properties provided are located in France and Spain (around 30k properties).

Technical information

Poplidays provides a JSON/XML API. Some endpoints are publicly accessible while others require authentication with a client key. The authentication process for GET requests is well described here. For POST requests procedure is the same except that we should sign only the path with client key (without POST params) and then add the sign to URL as GET parameters (following by ?). More details can be found in Poplidays::Commands::BaseCommand#remote_call method.

To request JSON-encoded responses, requests should include the Accept: application/json header on the HTTP request.

Poplidays' API is located at https://api.poplidays.com

Poplidays' sandbox API is located at https://api.preprod.poplidays.com

Official Documentation:

  • Poplidays REST API Documentation: http://dev.poplidays.com/index.html. This page includes all information that should be necessary for implementing the whole booking process with Poplidays.

Quoting Prices

Checking if a property is available and getting the price is good described in Poplidays' communication schema, steps 5 and 6.

It's done by invoking booking/easy endpoint in EVALUATION mode. The response of that request will simply evaluate availability and proposed the best pricing for the deal.

The request requires authentication.

Request

POST /v2/bookings/easy

{  
  "requestType": "EVALUATION", // just calculate the best price
  "lodgingId": "8927439190",   // property id
  "arrival": "20161028",
  "departure": "20161206",
  "occupantCount": "2",        // guests count
  "customer": {                // all customer fields are required but can be empty in EVALUATION mode
    "address": {"line1":"", "city":"", "country":"", "postalCode":""},
    "email":"",
    "firstName":"",
    "lastName":"",
    "language":"",
    "phoneNumber":""
  }
}

Success response

{
  "value": 3410.28,
  "ruid": "09cdecc64b5ba9504c08bb598075262f"
}

Error response

If stay specified in booking is no more available, response status code will be 409 (conflict).

{
  "code": 409,
  "message": "Lodging is no more available",
  "ruid": "65a8930693af51afd5e90b0f3dfea805"
}

When arrival or departure date is invalid, response status code will be 400.

{
  "code": 400,
  "message": "Unauthorized arriving day",
  "ruid": "76b95928b4fec0ca2dc6ddb33e89b044"
}

In both cases we should return quotation with availability = false.

Mandatory Services

Apart from the value field retrieved in the call above, it is also required to account for possible mandatory services that might be applicable to a property. Unfortunately, the price for these services are only retrievable through the property details API.

Request

https://api.poplidays.com/v2/lodgings/709328683
  • 709328683 is the property ID on Poplidays (or lodging ID, as they call it.)

Response (sample)

{
    "address": {
        "city": "Javea",
        "country": "Espagne",
        "line1": "Javea",
        "line2": "Costa Blanca",
        "line3": "",
        "postalCode": "03730"
    },
    "bathrooms": 5,
    "bedrooms": 7,
    "carRequired": "EMPTY",
    "caution": "400.0",
    "city": "Javea",
    // ...
    "id": 709328683,
    "lastChange": "2016-03-08 15:28",
    "latitude": 38.744988,
    "licenceAgreement": null,
    "longLabel": "Location Maison El Nido - Javea, 9 pi\u00e8ces, 14 personnes",
    "longitude": 0.206809,
    "mandatoryServicesPrice": 25.0,
    "mediumLabel": "Location Maison Javea, 9 pi\u00e8ces, 14 personnes",
    "minWeekBasePrice": 1942.0,
    "minWeekPrice": 1942.0,
    "minWeekPromotion": 0.0,
    "name": "El Nido",
    "personMax": 14,
    "photos": [
      // ...
    ],
    "priceEnabled": true,
    "reference": "API-1-20-1636",
    "requestOnly": false,
    "rooms": 9,
    "shortLabel": "Location Maison, 9 pi\u00e8ces, 14 personnes",
    "standing": 3,
    "subType": "APARTMENT",
    "surface": 300,
    "surroundings": [],
    "type": "HOUSE",
    "url": "https://www.poplidays.com/fr/product/709328683",
    "zipCode": "03730"
}

The only field that matters for price calculation in this response is the mandatoryServicesPrice field (`25.0 in the example above). The final price for a stay, hence, should be:

finalPrice = value + mandatoryServicesPrice

Prices are always quoted in EUR.

Booking

Booking is good described in Poplidays' communication schema, steps 7 and 8.

It's done by invoking booking/easy endpoint in BOOKED mode.

The request requires authentication.

Request

POST /v2/bookings/easy

{
  "requestType": "BOOKED",
  "lodgingId": "5012225801",
  "arrival": "20160921",
  "departure": "20161004",
  "occupantCount": 1,
  "price": 1209,              // Should be equal or higher than Poplidays possible price
  "customer": {               // All customer fields are required, but can be blank. 
    "address": {              // Roomorama webhook provides not all params.
      "line1": "",
      "city": "",
      "country": "",
      "postalCode": ""
    },
    "email": "developers@roomorama.com",
    "firstName": "Roomorama",
    "lastName": "Guest",
    "language": "",
    "phoneNumber": "+1 93849238",
    "civility": ""
  }
}

Success response

{
  "id": 9257079406, // booking id, the value we save to DB
  "reference": "CHD00001",
  "ruid": "f211687c1e88e065e3331cacebe4803c"
}

Error response

If stay specified in booking is no more available, response status code will be 409 (conflict).

{
  "code": 409,
  "message": "Lodging is no more available",
  "ruid": "65a8930693af51afd5e90b0f3dfea805"
}

If the presented price less than Poplidays' possible price, response status code will be 404 (not found).

{
  "code": 404,
  "message": "Price too low"
}

When arrival or departure date is invalid, response status code will be 400.

{
  "code": 400,
  "message": "Unauthorized arriving day",
  "ruid": "76b95928b4fec0ca2dc6ddb33e89b044"
}

Prices are always quoted in EUR.

Synchronisation

The sync process is executed by two workers:

  • Properties metadata sync Workers::Suppliers::Poplidays::Metadata
  • Properties availabilities sync Workers::Suppliers::Poplidays::Calendar

Metadata

Metadata sync uses next Poplidays API methods (wrapped by Poplidays::Importer class) to create Roomorama::Property instances:

  • lodgings - fetches list of properties with general information (this call gets a lot of time >100sec and returns a big response >75mb) Roomorama has special endpoint for this method lodgings/out/Roomorama
  • lodging - fetches details for each property
  • availabilities - fetches property availability information, used to fill nightly/weekly/monthly_rate information
  • extras - fetches property extras, used to get cleaning service info. Because cleaning is additional information, request to this method is optional, if it fails property will be synced anyway.

Some Poplidays' properties don't support instant booking (requestOnly = true) or has price available only through their call center (priceEnabled = false), we don't sync such properties.

In case when a list of property availabilities is empty we also halt the property sync process.

Calendar

Calendar sync uses next Poplidays API methods (wrapped by Poplidays::Importer class) to create Roomorama::Calendar instance:

  • lodging - fetches details for each property, used to get mandatory_services_price and calculate nightly_rate
  • availabilities - fetches property availabilities information, used to calculate nightly_rate

They have an price/availability for each checkin/checkout pair, called stay. Every stay from availabilities may not support instant booking (requestOnly = true) or may have price available only through Poplidays' call center (priceEnabled = false). Such stays should be marked as unavailable. If a date is not in any stay it also marked as unavailable.

Clone this wiki locally