Quick start

This guide walks you through your first call to the Best Price API. You will set up OAuth 1.0 signing, send a request to the Calendar endpoint, and inspect the response.

No credentials yet? Import the API collections and run any request against the mock environment straight away, with no credentials. Add your OAuth 1.0 credentials when you are ready to call the live API.

Prerequisites

Get the following from D-EDGE before starting:

OAuth 1.0 credentials: consumer key, consumer secret, token key, and token secret.
API base URL: the base URL for your environment.
Hotel ID and Group ID: the hotel you want to query.

All are delivered during the build step of your integration journey, after the partnership agreement.

Install an OAuth 1.0 library

Use a battle-tested library to handle the signing. Skip this step if you only use cURL.

npm install oauth-1.0a

pip install requests-oauthlib

composer require guzzlehttp/oauth-subscriber

dotnet add package RestSharp

<dependency>
    <groupId>oauth.signpost</groupId>
    <artifactId>signpost-commonshttp4</artifactId>
    <version>2.1.1</version>
</dependency>

Make your first call

Send a POST to the Calendar endpoint with a minimal request body. The exact field requirements are documented in the Reference. The four other Best Price endpoints follow the same authentication pattern; mind the guests field, whose shape (single object or array) changes per endpoint.

curl --request POST \
  --url https://{apiBaseUrl}/Planning/2018A/BestPrice/Calendar \
  --header 'Authorization: OAuth oauth_consumer_key="YOUR_CONSUMER_KEY",
    oauth_token="HOTEL_TOKEN_KEY",
    oauth_signature_method="HMAC-SHA1",
    oauth_timestamp="1714128000",
    oauth_nonce="abc123",
    oauth_version="1.0",
    oauth_signature="..."' \
  --header 'Content-Type: application/json' \
  --data '{
    "beginDate": "YYYY-MM-DD",
    "endDate": "YYYY-MM-DD",
    "guests": [{"adults": 2}],
    "filter": {
      "ratePlan": {"hotelId": <hotelId>, "groupId": <groupId>},
      "currency": "EUR"
    }
  }'

import OAuth from "oauth-1.0a";
import crypto from "crypto";

const oauth = OAuth({
  consumer: {
    key: process.env.DEDGE_CONSUMER_KEY,
    secret: process.env.DEDGE_CONSUMER_SECRET,
  },
  signature_method: "HMAC-SHA1",
  hash_function(base_string, key) {
    return crypto.createHmac("sha1", key).update(base_string).digest("base64");
  },
});

const token = {
  key: process.env.DEDGE_TOKEN_KEY,
  secret: process.env.DEDGE_TOKEN_SECRET,
};

const url = "https://{apiBaseUrl}/Planning/2018A/BestPrice/Calendar";
const body = {
  beginDate: "YYYY-MM-DD",
  endDate: "YYYY-MM-DD",
  guests: [{ adults: 2 }],
  filter: {
    ratePlan: { hotelId: <hotelId>, groupId: <groupId> },
    currency: "EUR",
  },
};

const response = await fetch(url, {
  method: "POST",
  headers: {
    ...oauth.toHeader(oauth.authorize({ url, method: "POST" }, token)),
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});

console.log(response.status, await response.json());

import os
from requests_oauthlib import OAuth1Session

session = OAuth1Session(
    client_key=os.environ["DEDGE_CONSUMER_KEY"],
    client_secret=os.environ["DEDGE_CONSUMER_SECRET"],
    resource_owner_key=os.environ["DEDGE_TOKEN_KEY"],
    resource_owner_secret=os.environ["DEDGE_TOKEN_SECRET"],
)

response = session.post(
    "https://{apiBaseUrl}/Planning/2018A/BestPrice/Calendar",
    json={
        "beginDate": "YYYY-MM-DD",
        "endDate": "YYYY-MM-DD",
        "guests": [{"adults": 2}],
        "filter": {
            "ratePlan": {"hotelId": <hotelId>, "groupId": <groupId>},
            "currency": "EUR",
        },
    },
)

print(response.status_code)
print(response.json())

require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Subscriber\Oauth\Oauth1;

$stack = HandlerStack::create();

$middleware = new Oauth1([
    'consumer_key'    => getenv('DEDGE_CONSUMER_KEY'),
    'consumer_secret' => getenv('DEDGE_CONSUMER_SECRET'),
    'token'           => getenv('DEDGE_TOKEN_KEY'),
    'token_secret'    => getenv('DEDGE_TOKEN_SECRET'),
]);

$stack->push($middleware);

$client = new Client([
    'base_uri' => 'https://{apiBaseUrl}/',
    'handler'  => $stack,
    'auth'     => 'oauth',
]);

$response = $client->post('Planning/2018A/BestPrice/Calendar', [
    'json' => [
        'beginDate' => 'YYYY-MM-DD',
        'endDate'   => 'YYYY-MM-DD',
        'guests'    => [['adults' => 2]],
        'filter'    => [
            'ratePlan' => ['hotelId' => <hotelId>, 'groupId' => <groupId>],
            'currency' => 'EUR',
        ],
    ],
]);

echo $response->getStatusCode() . "\n";
echo $response->getBody();

using RestSharp;
using RestSharp.Authenticators.OAuth;

var options = new RestClientOptions("https://{apiBaseUrl}/Planning/2018A")
{
    Authenticator = OAuth1Authenticator.ForProtectedResource(
        consumerKey: Environment.GetEnvironmentVariable("DEDGE_CONSUMER_KEY"),
        consumerSecret: Environment.GetEnvironmentVariable("DEDGE_CONSUMER_SECRET"),
        token: Environment.GetEnvironmentVariable("DEDGE_TOKEN_KEY"),
        tokenSecret: Environment.GetEnvironmentVariable("DEDGE_TOKEN_SECRET"),
        signatureMethod: OAuthSignatureMethod.HmacSha1)
};
var client = new RestClient(options);

var request = new RestRequest("/BestPrice/Calendar", Method.Post);
request.AddJsonBody(new
{
    beginDate = "YYYY-MM-DD",
    endDate = "YYYY-MM-DD",
    guests = new[] { new { adults = 2 } },
    filter = new
    {
        ratePlan = new { hotelId = <hotelId>, groupId = <groupId> },
        currency = "EUR"
    }
});

var response = await client.ExecuteAsync(request);
Console.WriteLine(response.StatusCode);
Console.WriteLine(response.Content);

import com.fasterxml.jackson.databind.ObjectMapper;
import oauth.signpost.OAuthConsumer;
import oauth.signpost.commonshttp.CommonsHttpOAuthConsumer;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;

import java.util.List;
import java.util.Map;

OAuthConsumer consumer = new CommonsHttpOAuthConsumer(
    System.getenv("DEDGE_CONSUMER_KEY"),
    System.getenv("DEDGE_CONSUMER_SECRET")
);
consumer.setTokenWithSecret(
    System.getenv("DEDGE_TOKEN_KEY"),
    System.getenv("DEDGE_TOKEN_SECRET")
);

ObjectMapper mapper = new ObjectMapper();
String body = mapper.writeValueAsString(Map.of(
    "beginDate", "YYYY-MM-DD",
    "endDate", "YYYY-MM-DD",
    "guests", List.of(Map.of("adults", 2)),
    "filter", Map.of(
        "ratePlan", Map.of("hotelId", <hotelId>, "groupId", <groupId>),
        "currency", "EUR"
    )
));

HttpPost request = new HttpPost("https://{apiBaseUrl}/Planning/2018A/BestPrice/Calendar");
request.setEntity(new StringEntity(body, "UTF-8"));
request.setHeader("Content-Type", "application/json");
consumer.sign(request);

try (CloseableHttpClient client = HttpClients.createDefault()) {
    client.execute(request);
}

Inspect the response

A successful response returns 200 OK with a JSON array. Each item represents one arrival date in your requested range, with availability and pricing.

[
  {
    "arrivalDate": "2026-12-07",
    "minimumStay": 1,
    "maximumStay": 4,
    "totalPrice": 100,
    "currency": "EUR",
    "hotelAvailability": 25,
    "status": "Available",
    "unavailabilityReason": "None",
    "closedOnDeparture": false,
    "rateId": 12345,
    "rooms": [
      {
        "roomId": 67890,
        "availability": 4,
        "guests": {
          "adults": 2,
          "children": [],
          "infants": 0
        }
      }
    ]
  },
  {
    "arrivalDate": "2026-12-08",
    "minimumStay": 1,
    "maximumStay": 4,
    "totalPrice": 110,
    "currency": "EUR",
    "hotelAvailability": 24,
    "status": "Available",
    "unavailabilityReason": "None",
    "closedOnDeparture": false,
    "rateId": 12345,
    "rooms": [
      {
        "roomId": 67890,
        "availability": 3,
        "guests": {
          "adults": 2,
          "children": [],
          "infants": 0
        }
      }
    ]
  }
]

See the response schema for the full structure.

Common issues

Status	Likely cause	Where to look
`401`	Signing issue: invalid credentials, clock drift, or reused nonce	Authentication
`400`	Validation error: malformed body or missing field	Responses
`403`	Token does not grant access to this hotel	Contact us

Next steps

Reference

Endpoint specifications, parameters, and response schemas.

Use cases

Build calendars, listings, multi-property views, and member rate widgets.

Best practices

Patterns to build responsibly and run reliably at scale.

Get started

Build

Resources

Prerequisites

Install an OAuth 1.0 library

Make your first call

Inspect the response

Common issues

Next steps

Reference

Use cases

Best practices

​Prerequisites

Install an OAuth 1.0 library

Make your first call

Inspect the response

​Common issues

​Next steps

Reference

Use cases

Best practices

Prerequisites

Common issues

Next steps