Introduction

Welcome to the ORS APIv2 reference. This guide explains the ORS application programming interface (API). It describes various API operations, requests, response structures and errors.

The API is REST-like with data exchanged in JSON format.

Please read the rest of this introduction before continuing onto specific API operations.

API Access & Authentication

The API endpoint is accessible at the https://api.ors.si/crs/v2/.

Every interaction with ORS API requires authentication information to be present. This is done in form of adding X-API-Key HTTP Header to every request to ORS API.

This API key is used to uniquely identify the sender of a request and as such it should be kept a secret.

Request IDs

All requests to ORS API are assigned a unique ID that is used to track and log requests as they are being processed. This ID is also being exported to you in the form of an X-Request-ID HTTP header. It is also included in every JSON output as RequestID key.

We recommend that in case of any issues with our API to include the request ID(s) returned by our API, especially in case of performance issues.

Setting language

You can set your preferred language by setting Accept-Language HTTP header.

List of valid values for this HTTP header can be seen in languages collection.

Alternatively you can also set your preferred langauge in form of adding HTTP GET language argument to your request URI. If both GET argument and HTTP header are present, GET arugment is preferred.

If no langauge is set, default is set to en.

Rate limiting

API Limits the number of requests you can make using a token bucket model.

Token bucket model works by running a "bucket" of tokens for each API key. A new token is added into the bucket every 100 milliseconds. This bucket is limited in size and can hold up to 500 tokens. When the bucket is full, new tokens are discarded.

Every time you send a request to our API a token is removed from your bucket. When the number of tokens in your bucket reaches 0, the request is denied with an error until the number of tokens in a bucket is again above 0.

This in practice limits baseline request rate to 10 requests/second while still allowing for bursts above the given baseline. The bigger the burst, the less time that burst can be maintained until requests start being denied.

Number of tokens you have available is send in every response using X-Requests-Left HTTP Header.

Search and booking guidelines

We generally recommend starting every search with a region request. This request returns all regions where offers for your query were found and the minimum price for each region.

From the results of that request, you can then use products request with the same search parameters, but adding one of the regions returned in the regions request (user-selected region). This request will return a list of all offers found in that region.

When a user selects an offer you can use dates request to show actual bookable dates to a user for the selected offer, either by sending its GIATA code or if not present by sending TourOperator and hotel code for that offer.

Once a user selects a date, you can use verify request to check whenever the offer is actually available at the tour operator and get accurate pricing. While we strive to have the most accurate and up-to-date information, tour operators can still change offer availability between our database updates or have additional fees that are unknown to us. To do so, you have to use verify request with tour operator code and hash code for that date. The pricing information for this request is returned directly from the tour operator system.

Finally, you can use register method to register a booking in our system, or book method to book directly with the tour operator.

To recap;

• Start search with regions with base search paramaters.

• Use products to display offers to user from one of the regions returned by regions query.

• Use dates to display bookable dates to user from one of the offers returned by the products query.

• Use verify to check for selected offer availability and pricing information.

• Use register or book method to make a booking in our system.

Sample code

This is a small sample on how you can communicate with API using PHP:

function sendRq($target, $rq)
{
  return json_decode(file_get_contents(
    "https://api.ors.si/crs/v2/".implode("/", array_map("rawurlencode", explode("/", $target))),
    false, stream_context_create(array("http" => array(
      "header"  => "X-API-Key: 76e3d60e029cb8ee9b45ecd959151f35\r\n".
                   "Accept-Language: si\r\n".
                   "Content-type: application/json\r\n",
      "method"  => "POST",
      "content" => json_encode($rq),
    )))
  ), true);
}

$res = sendRq("search/hotel/dates", array(
  "Filter" => array(
    "TourOperator" => array("PALM", "KOMP"),
    "RoomType"     => array("DZ"),
  ),
  "Sort" => array(
    array("OfferName" => "asc"),
  ),

  "Page"          => 0,
  "Count"         => 30,
  "StartDate"     => "10.12.2019",
  "EndDate"       => "23.02.2020",
  "AdultCount"    => 2,
  "GiataID"       => [34649, 6711],
  "RegionGroup"   => 100023,
  "MinDuration"   => 1,
  "MaxDuration"   => 14,
));