Documentation: Fresh Cache API

With this API, you can identify which hotel searches have experienced price or availability changes in Veturis. This information is highly useful for updating your Veturis cache or even invalidating your cache with other providers, thereby improving your cache quality. By default, the API reports availabilities with price or availability changes within the last 24 hours. The API includes up to the last 10000 availabilities that have changed.

API Endpoint

Request Parameters

Parameter	Type	Required	Description
`password`	string	Yes	The password for authenticating the request.
`asXML`	boolean	No	If set to `true`, the response includes cache data in XML format.
`all`	boolean	No	If set to `true`, the response includes both updated caches and new caches created for the first time.
`updateCacheMax`	integer	No	The maximum number of seconds that a cache update is considered a price change. By default, this is set to 24 hours (86400 seconds). If the updated cache exceeds this value, it is treated as a new cache and not a change in availability. The higher the value, the more availabilities will appear in the listing. If your cache is only a few hours old, you should adjust this value accordingly to process fewer caches.

The parameters must be sent by POST protocol, for example in linux, curl -X POST https://fresh.cache.veturis.com:/yourEndPoint.php -d 'password=yourPassword' -d 'updateCacheMax=36000'

The all parameter additionally includes updated availabilities for which there was no previous quote. These can be significantly more, so it is recommended to use this option only in coordination with Veturis. With it, you can retrieve all cache updates from Veturis, including not only caches with price and availability changes but also new prices.

The updateCacheMax parameter limits how old a cache can be to be considered a price change.

Response Format

The API returns data in either JSON or XML format, depending on the request parameters.

JSON Response

By default, the response includes only updated caches in JSON format. Each line consists of two fields separated by a colon (:):

XML Response

If the asXML parameter is set to true, the second field of each line is an XML document. This document provides a precise cache query format for the Veturis system.

How to Use the API

The API should be called with high frequency, for example, every second. The API maintains a queue of the most recently updated caches. Once you retrieve the updated caches from Veturis, launch the availability queries to Veturis SearchAvailabilityRQ API to get new quotes.

Notes for Implementation

The following examples demonstrate how to implement a continuous loop to retrieve requests and process them in parallel using the API. Select the desired programming language:

PHP Example

<?php
/************************************************
 * EXAMPLE SCRIPT IN PHP (ALL IN ENGLISH)
 ************************************************/

/**
 * 0) Configuration for the request to fresh cache
 */
$initialApiUrl     = "https://fresh.cache.veturis.com:/yourEndPoint.php";
$freshCachePassword  = "password_freshcache"// Replace with your actual password
$asXml             = "true";           // We want the response in XML format
$secondsUpdateCacheMax = 3600*6;  //We want only caches that have changed price in last 24h


/**
 * 1) Configuration for the request to Veturis SearchAvailability API, you already have this keys
 */
$veturisUrl       = "https://xmlservices.veturis.com/xmlWebServices.php";
$user             = "Veturis_api_user";        // Replace with your real user
$pass             = "user_pass";    // Replace with your real password
$agencyUser       = "agencyUser_name";      // Replace with your real agency user
$agencyPassword   = "agencyUser_password";  // Replace with your real agency password

/**
 * 2) Function to fetch and parse requests from tour_end_point.php
 *    Each line in the response has the format:
 *    ":"
 */
function getRequestsFromFreshCache($apiUrl, $password, $asXml, $secondsUpdateCacheMax) {
    // Prepare POST fields
    $postFields = [
        'password' => $password,
        'asXML'    => $asXml,
        'updateCacheMax'    => $secondsUpdateCacheMax
    ];

    // Initialize cURL
    $ch = curl_init($apiUrl);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $postFields);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    // Execute and retrieve the response
    // Each line looks like: "8132:"
    $response = curl_exec($ch);
    curl_close($ch);
    //printf($response); //For debugging reason comment it in production

    // Separate the response by lines
    $lines = explode("\n", $response);

    // Parse each line to extract the cache seconds and the XML
    $requests = [];
    foreach ($lines as $line) {
        $line = trim($line);
        if ($line === '') {
            continue; // Skip empty lines
        }

        // Use explode with limit=2 to split at the first colon only
        $parts = explode(':', $line, 2);
        if (count($parts) < 2) {
            continue; // Not well-formed, ignore
        }

        $cacheSeconds = trim($parts[0]);
        $xml = trim($parts[1]);

        $requests[] = [
            // First parameter is not an ID; it represents
            // how many seconds the cache was freshly updated.
            'cache_seconds' => $cacheSeconds,
            'xml'           => $xml
        ];
    }

    return $requests;
}

/*
 * Process the given requests in parallel (150 at a time),
 * handling each response as soon as it becomes available.
 *
 * @param array  $requests         An array of requests; each request must have 'xml'
 * @param string $user             Veturis user
 * @param string $password         Veturis password
 * @param string $agencyUser       Agency user
 * @param string $agencyPassword   Agency password
 * @param string $veturisUrl       URL endpoint for Veturis
 */
function processRequestsInParallel($requests, $user, $password, $agencyUser, $agencyPassword, $veturisUrl)
{
    // Break the array of requests into chunks of 150
    $chunks = array_chunk($requests, 50);

    foreach ($chunks as $chunk) {
        // Initialize the multi_curl handle
        $multiCurl = curl_multi_init();

        // Keep track of all cURL handles so we can manage them
        $curlHandles = [];

        // Create a cURL handle for each request
        foreach ($chunk as $request) {
            $xmlRQ = $request['xml'];

            // Prepare the POST data
            $postFields = [
                'xmlRQ'          => $xmlRQ,
                'user'           => $user,
                'password'       => $password,
                'agencyUser'     => $agencyUser,
                'agencyPassword' => $agencyPassword
            ];

            // Initialize a single cURL handle
            $ch = curl_init($veturisUrl);
            curl_setopt($ch, CURLOPT_POST, true);
            curl_setopt($ch, CURLOPT_POSTFIELDS, $postFields);
            curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

            // Add the handle to the multi handle
            curl_multi_add_handle($multiCurl, $ch);
            $curlHandles[] = $ch;
        }

        // Track whether there are still active transfers
        $active = null;

        // Execute all requests in parallel, but process as soon as each one finishes
        do {
            // Run the multi_curl
            $mrc = curl_multi_exec($multiCurl, $active);

            // Check if there is any completed request
            while ($info = curl_multi_info_read($multiCurl)) {
                if ($info['msg'] === CURLMSG_DONE) {
                    // One of the requests has finished
                    $finishedHandle = $info['handle'];

                    // Get the response from the finished handle
                    $response = curl_multi_getcontent($finishedHandle);

                    // ---------------------------------------------
                    // Here is where you can:
                    //   - Save $response to a database
                    //   - Cache it
                    //   - Process or parse the response
                    //   - etc.
                    // ---------------------------------------------
                    // Example:
                    // echo "Response:\n$response\n\n";

                    // Remove the handle from the multi handle
                    curl_multi_remove_handle($multiCurl, $finishedHandle);
                    // Close the finished handle
                    curl_close($finishedHandle);
                }
            }

            // If there are still active handles, wait for activity
            if ($active) {
                curl_multi_select($multiCurl);
            }

        } while ($active && $mrc == CURLM_OK);

        // At this point, all handles in this chunk are done
        // (because we remove each as it finishes)
        echo "[INFO] " . count($chunk) . " requests processed.\n";

        // Close the multi-curl
        curl_multi_close($multiCurl);
    }
}

/**
 * 4) Main loop (continuous example to Veturis SearchAvailability)
 */
while (true) {
    // a) Retrieve requests from tour_end_point.php
    printf("[INFO] Quering FreshCache.\n");
    $elapsedTime=microtime(true);
    $requests = getRequestsFromFreshCache($initialApiUrl, $freshCachePassword, $asXml,$secondsUpdateCacheMax);

    if (empty($requests)) {
        echo "[INFO] No requests received. Waiting 1 seconds...\n";
        sleep(1);
        continue;
    }
    else{
            printf("[INFO] ". count($requests). " caches from FreshCache.\n");
    }
    processRequestsInParallel($requests, $user, $pass, $agencyUser, $agencyPassword, $veturisUrl);
    echo "[INFO] Iteration completed in ". (microtime(true)-$elapsedTime) ." seconds.\n";
}
?>

Go Example


package main


import (
    "io/ioutil"
    "fmt"
    "net/http"
    "net/url"
    "strings"
    "sync"
    "time"
)

// -----------------------------------------------------------------------------
// 0) Configuration for the request to FreshCache
// -----------------------------------------------------------------------------
var (
    // URL where the FreshCache requests will be retrieved from
    initialApiURL           = "https://fresh.cache.veturis.com:/tourMind.php"
    // Replace with your actual FreshCache password
    freshCachePassword      = "password_freshcache"
    // We want the response in XML format
    asXML                   = "true"
    // We only want caches that changed in the last 6 hours (3600 * 6)
    secondsUpdateCacheMax   = 3600 * 6

    // 1) Configuration for the Veturis SearchAvailability API
    // Replace these credentials with actual working user/password
    veturisURL              = "https://xmlservices.veturis.com/xmlWebServices.php"
    user                    = "Veturis_api_user"
    pass                    = "user_pass"
    agencyUser              = "agencyUser_name"
    agencyPassword          = "agencyUser_password"
)

// Request is a struct representing each line of data retrieved from FreshCache
type Request struct {
    CacheSeconds string
    XML          string
}

// -----------------------------------------------------------------------------
// getRequestsFromFreshCache sends a POST request to FreshCache and parses each
// line of the response. The returned lines have the format:
// "<cache_seconds><xml version="1.0" encoding="UTF-8"?><SearchAvailabilityRQ ...>
// -----------------------------------------------------------------------------
func getRequestsFromFreshCache(
    apiURL string,
    password string,
    asXML string,
    secondsUpdateCacheMax int,
) ([]Request, error) {

    // Build POST form data
    data := url.Values{}
    data.Set("password", password)
    data.Set("asXML", asXML)
    data.Set("updateCacheMax", fmt.Sprintf("%d", secondsUpdateCacheMax))

    // Execute POST request
    resp, err := http.PostForm(apiURL, data)
    if err != nil {
        return nil, fmt.Errorf("error performing POST to FreshCache: %w", err)
    }
    defer resp.Body.Close()

    // Read the response content
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        return nil, fmt.Errorf("error reading FreshCache response: %w", err)
    }

    // Split the response by lines
    lines := strings.Split(string(body), "\n")
    var requests []Request

    // Parse each line, splitting into: "<cache_seconds> and "<xml>
    for _, line := range lines {
        line = strings.TrimSpace(line)
        if line == "" {
            continue
        }

        parts := strings.SplitN(line, ":", 2)
        if len(parts) < 2 {
            // Not well-formed; ignore the line
            continue
        }

        cacheSeconds := strings.TrimSpace(parts[0])
        xmlContent := strings.TrimSpace(parts[1])

        // Store in our custom struct
        requests = append(requests, Request{
            CacheSeconds: cacheSeconds,
            XML:          xmlContent,
        })
    }

    return requests, nil
}

// -----------------------------------------------------------------------------
// processRequestsInParallel processes the given requests in parallel,
// in chunks of size `chunkSize`. Inside each chunk, it creates one goroutine
// per request to send it to Veturis.
// -----------------------------------------------------------------------------
func processRequestsInParallel(
    requests []Request,
    user string,
    password string,
    agencyUser string,
    agencyPassword string,
    veturisURL string,
    chunkSize int,
) {
    // Break the array of requests into smaller chunks
    for i := 0; i < len(requests); i += chunkSize {
        end := i + chunkSize
        if end > len(requests) {
            end = len(requests)
        }
        chunk := requests[i:end]

        // Use a WaitGroup to wait for all goroutines in this chunk
        var wg sync.WaitGroup

        for _, req := range chunk {
            wg.Add(1)
            go func(r Request) {
                defer wg.Done()

                // Execute the actual POST call to Veturis
                err := doVeturisRequest(r, user, password, agencyUser, agencyPassword, veturisURL)
                if err != nil {
                    // In production, you would handle or log this error
                    // fmt.Printf("Error on doVeturisRequest: %v\n", err)
                }

            }(req)
        }

        // Wait for all goroutines in this chunk to finish
        wg.Wait()

        // Inform how many requests were processed in this chunk
        fmt.Printf("[INFO] %d requests processed.\n", len(chunk))
    }
}

// -----------------------------------------------------------------------------
// doVeturisRequest performs the POST request for a single Request (XML payload)
// to the Veturis endpoint.
// -----------------------------------------------------------------------------
func doVeturisRequest(
    req Request,
    user string,
    password string,
    agencyUser string,
    agencyPassword string,
    veturisURL string,
) error {
    // Build the POST data
    data := url.Values{}
    data.Set("xmlRQ", req.XML)
    data.Set("user", user)
    data.Set("password", password)
    data.Set("agencyUser", agencyUser)
    data.Set("agencyPassword", agencyPassword)

    // Execute the POST request
    resp, err := http.PostForm(veturisURL, data)
    if err != nil {
        return fmt.Errorf("error performing POST to Veturis: %w", err)
    }
    defer resp.Body.Close()

    // Read the response from Veturis
    result, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        return fmt.Errorf("error reading Veturis response: %w", err)
    }

    // You can store, cache, or process the response here as needed
    // Example: just ignore it, or uncomment for debugging:
    // fmt.Printf("Veturis response:\n%s\n\n", string(result))

    _ = result // Avoids unused variable warning

    return nil
}

// -----------------------------------------------------------------------------
// main is the continuous loop that:
// 1) Fetches requests from FreshCache
// 2) Processes them in parallel against Veturis
// -----------------------------------------------------------------------------
func main() {
    // Infinite loop to continuously poll FreshCache and process requests
    for {
        fmt.Println("[INFO] Querying FreshCache.")
        start := time.Now()

        // Fetch requests from FreshCache
        requests, err := getRequestsFromFreshCache(initialApiURL, freshCachePassword, asXML, secondsUpdateCacheMax)
        if err != nil {
            fmt.Printf("[ERROR] getRequestsFromFreshCache: %v\n", err)
            // Wait a bit before trying again
            time.Sleep(2 * time.Second)
            continue
        }

        // If no requests arrived, wait and try again
        if len(requests) == 0 {
            fmt.Println("[INFO] No requests received. Waiting 1 second...")
            time.Sleep(1 * time.Second)
            continue
        } else {
            fmt.Printf("[INFO] %d caches from FreshCache.\n", len(requests))
        }

        // Process the requests in parallel, with a chunk size of 50
        processRequestsInParallel(requests, user, pass, agencyUser, agencyPassword, veturisURL, 50)

        // Measure how long the iteration took
        elapsed := time.Since(start)
        fmt.Printf("[INFO] Iteration completed in %.2f seconds.\n", elapsed.Seconds())
    }
}