Skip to content

Kigo

Jump to bottom
Keang edited this page Feb 9, 2017 · 6 revisions

Kigo (also known as Kigo Real Page) is a supplier with properties all over the world. At the time of this writing, the countries with the largest number of properties are, in order: Croatia, Spain, Italy, France and United States.

Technical information

Kigo currently supports two different APIs:

  • Kigo Channels API
  • Kigo Legacy API

The former is the current and most up to date version of their API. However, both APIs are pretty similar and the request/response formats have minor differences. Still, both endpoints need to be supported since properties that were retrieved by the Legacy API cannot be queried against the new, Channels API (and vice-versa.)

All Kigo API calls are performed through POST requests with JSON-encoded bodies (Content-Type must be properly set to application/json).

Kigo Channels API is located at https://www.kigoapis.com. Kigo Legacy API is located at https://app.kigo.net.

Official Documents:

  • API Development Introduction - outlines the flow required to perform an integration with Kigo, with FAQ.
  • Kigo Channels API - v1 - technical documentation of the provided endpoints. While this document describes the Kigo Channels API, differences related to the Kigo Legacy API are also documented.

Authentication

Authentication happens differently on the Channels and Legacy APIs. The former authenticates the caller by checking a subscription-key query string parameter appended to the URL of every API call. The latter uses HTTP Basic Authentication with a username and password combination.

Quoting Prices

Checking if a property is available and calculating the price for a stay is currently performed by calling the computePricing API call.

  • Kigo Channels API: POST https://www.kigoapis.com/channels/v1/computePricing?subscription-key=...
  • Kigo Legacy API: POST https://app.kigo.net/api/ra/v1/computePricing (with HTTP Basic Auth headers properly set)

Kigo Channels API: Request

{
  "PROP_ID"        => "4309",
  "RES_CHECK_IN"   => "2016-04-05",
  "RES_CHECK_OUT"  => "2-16-04-09",
  "RES_N_ADULTS"   => 3,
  "RES_N_CHILDREN" => 0
}
  • PROP_ID is the property ID in their system. It is always numerical.
  • RES_CHECK_IN is the check-in date.
  • RES_CHECK_OUT is the check-out date.
  • RES_N_ADULTS is the number of adult guests. Roomorama does not collect number of adults/children, so this is the number of guests provided by the caller.
  • RES_N_CHILDREN is the number of children. In Roomorama, this field will always be 0.

Kigo Legacy API: Request

{
  "PROP_ID"        => "4309",
  "RES_CREATE"     => "2016-03-08",
  "RES_CHECK_IN"   => "2016-04-05",
  "RES_CHECK_OUT"  => "2-16-04-09",
  "RES_N_ADULTS"   => 3,
  "RES_N_CHILDREN" => 0,
  "RES_N_BABIES"   => 0
}
  • RES_CREATE indicates the time the booking is being created. We default this value to the current date.
  • RES_N_BABIES is the number of babies. In Roomorama, this field will always be 0.

Response

The response returned by Kigo varies according to whether or not the property is available. The response sent back will always include an API_RESULT_CODE field indicating what the outcome was. The important ones are:

  • E_OK: the request was successful and the property is available. Pricing information is in the API_REPLY field.
  • E_NOSUCH: this result code is shared for two distinct error scenarios. It can indicate that the property ID was not found, or that the property is unavailable. To determine the latter, we inspect the content of the API_RESULT_TEXT field that, when the property is unavailable, will include a message stating so.
  • Any other result code constitutes a failure and should be handled as such.

Property is unavailable on the selected dates

{
  "API_CALL_ID"     => "779a4c12-2764-4274-a0a5-4df19382f015",
  "API_METHOD"      => "computePricing",
  "API_REPLY"       => null,
  "API_RESULT_CODE" => "E_NOSUCH",
  "API_RESULT_TEXT" => "The property was not found, or is unavailable (i.e. was deactivated). Unfortunately, this unit is not available for your selected period. Please try another unit.",
  "API_REVISION"    => 3,
  "API_VERSION"     => 1
}

Property is available on the selected dates

{
    "API_CALL_ID" => "20160304114457-fce31f3ada37f868c87c94616c3413e604649fd014fe00d0f92af0cdd906c99d",
    "API_METHOD"  => "computePricing",
    "API_REPLY"   => {
        "CURRENCY"                   => "EUR",
        "DEPOSIT_AMOUNT"             => "0.00",
        "DEPOSIT_DUE_DATE"           => null,
        "EXTRA_GUEST_CHARGES_AMOUNT" => "0.00",
        "FEES_AMOUNT"                => "0.00",
        "FEES_DUE_DATE"              => null,
        "RENT_AMOUNT"                => "570.00",
        "RENT_BASE_AMOUNT"           => "570.00",
        "RENT_DISCOUNTS_AMOUNT"      => "0.00",
        "RENT_DOWN_PMT_AMOUNT"       => "570.00",
        "RENT_DOWN_PMT_DUE_DATE"     => "2016-03-04",
        "RENT_FEES_AMOUNT"           => "0.00",
        "RENT_GUEST_CHARGES_AMOUNT"  => "0.00",
        "RENT_REM_PMT_AMOUNT"        => "0.00",
        "RENT_REM_PMT_DUE_DATE"      => null,
        "TOTAL_AMOUNT"               => "570.00"
    },
    "API_RESULT_CODE" => "E_OK",
    "API_RESULT_TEXT" => "",
    "API_REVISION"    => 14,
    "API_VERSION"     => 1
}

Property identifier not found

{
  "API_CALL_ID": "6a404761-820f-49bc-a505-ce988f44b534",
  "API_METHOD": "computePricing",
  "API_REPLY": null,
  "API_RESULT_CODE": "E_NOSUCH",
  "API_RESULT_TEXT": "The property was not found, or is unavailable (i.e. was deactivated).",
  "API_REVISION": 3,
  "API_VERSION": 1
}

Prices are quoted in EUR most of the times. Check the CURRENCY field on API_REPLY for the currency used in the quotation.

Create Booking

The create booking request is currently performed by calling the createConfirmedReservation API call.

  • Kigo Channels API: POST https://www.kigoapis.com/channels/v1/createConfirmedReservation?subscription-key=...
  • Kigo Legacy API: POST https://app.kigo.net/api/ra/v1/createConfirmedReservation (with HTTP Basic Auth headers properly set)

Kigo API: Request

{
  "PROP_ID"        => "123",
  "RES_CHECK_IN"   => "2016-04-05",
  "RES_CHECK_OUT"  => "2016-04-09",
  "RES_N_ADULTS"   => 3,
  "RES_N_CHILDREN" => 0,
  "RES_COMMENT"    => "Booking made via Roomorama on 2016-03-05",
  "RES_GUEST"      => {
    "RES_GUEST_EMAIL"     => "example@sample.com",
    "RES_GUEST_PHONE"     => "77-77-77",
    "RES_GUEST_COUNTRY"   => "RU",
    "RES_GUEST_LASTNAME"  => "Dulin",
    "RES_GUEST_FIRSTNAME" => "Ivan"
  }
}
  • PROP_ID is the property ID in their system. It is always numerical.
  • RES_CHECK_IN is the check-in date.
  • RES_CHECK_OUT is the check-out date.
  • RES_N_ADULTS is the number of adult guests. Roomorama does not collect number of adults/children, so this is the number of guests provided by the caller.
  • RES_N_CHILDREN is the number of children. In Roomorama, this field will always be 0.
  • RES_COMMENT is the comment for booking. Will be displayed in Kigo's reservation details.

Response

The response returned by Kigo varies according to whether or not the property is available. The response sent back will always include an API_RESULT_CODE field indicating what the outcome was. The important ones are:

  • E_OK: The call was successful, API_REPY holds an hash that contains a member called RES_ID, the id of the newly created reservation.
  • E_NOSUCH: It indicates that the property ID was not found
  • E_CONFLICT: Could not create reservation due to calendar conflict

Reservation has unavailable selected dates

{
  "API_CALL_ID"     => "779a4c12-2764-4274-a0a5-4df19382f015",
  "API_METHOD"      => "createConfirmedReservation",
  "API_REPLY"       => null,
  "API_RESULT_CODE" => "E_CONFLICT",
  "API_RESULT_TEXT" => "Dates not available",
  "API_REVISION"    => 3,
  "API_VERSION"     => 1
}

Successfully created reservation

{
  "API_CALL_ID"     => "779a4c12-2764-4274-a0a5-4df19382f015",
  "API_METHOD"      => "createConfirmedReservation"
  "API_RESULT_CODE" => "E_OK",
  "API_RESULT_TEXT" => "",
  "API_REVISION"    => 3,
  "API_VERSION"     => 1,
  "API_REPLY"       => {
    "RES_ID" => 12345
  },
}

Property identifier not found

{
  "API_CALL_ID": "6a404761-820f-49bc-a505-ce988f44b534",
  "API_METHOD": "createConfirmedReservation",
  "API_REPLY": null,
  "API_RESULT_CODE": "E_NOSUCH",
  "API_RESULT_TEXT": "The property was not found, or is unavailable (i.e. was deactivated).",
  "API_REVISION": 3,
  "API_VERSION": 1
}

Synchronisation

Kigo implements a diff api, which returns the ids of properties that have new contents/availabilities/rates changes since that last call.

We currently use the diff api to update both the metadata and availabilities of Kigo Real Page hosts, but only the availabilities of Kigo Legacy hosts. The diff api for properties metadata is not yet supported.

Refer to the following worker classes for more details:

  • Workers::Suppliers::Kigo::Metadata
  • Workers::Suppliers::Kigo::Availabilities
  • Workers::Suppliers::Kigo::Legacy::Metadata
  • Workers::Suppliers::Kigo::Legacy::Availabilities
Clone this wiki locally