CrystalRoof
CrystalRoof

Introduction

API Key

To make API calls to the Crystal Roof API, you need to provide an API key.

For initial testing, you may use the DEMO API key. The DEMO key allows testing methods in the W6 0 postcode sector or within the rectangle defined by [[51.492, -0.25], [51.502, -0.225]]. There is no calls per second limitation.

To use the Crystal Roof API for a broader area, contact us to obtain your personal API key. You must select your API package before obtaining the personal API key, and you will be entitled to 100 free API calls. The calls per second limitation will be identical to that of the selected package.

Calling Methods from API Documentation

You can call Crystal Roof API methods directly from the documentation pages. To do so, populate the request parameters and click the "Execute" option. By default, the system will use the DEMO API key. After obtaining of your personal API key you will be able to select it in the api_key dropdown.

REST

Crystal Roof API is organised around REST, designed to use predictable, resource-oriented URLs, and utilise HTTP status codes to indicate errors.

API Versioning

All Crystal Roof API methods are versioned.

In the details below, when we refer to an object, we mean the JSON root response object or any of its nested child objects, irrespective of their position in the tree hierarchy.

We introduce a new version to an existing API method for the following changes to the response JSON object:

  • Type of the object field changed, whether the old or new field type is a primitive type (numeric, string, boolean).
  • A field in the object is deleted.
  • A field that was non-nullable can now be null.

We are unlikely to introduce a new version to an existing API method in the following cases:

  • A new field is added to the object.
  • The ordering of the object fields is changed.
  • Data is updated.
  • The status code of the method changed.
  • The error message changed for unsuccessful methods.

Please do not rely on:

  • The ordering of the object fields.
  • The assumption that no new fields may appear in the object in the future.

If you are a user of a method that obtains a new version, we will notify you about that and give you details on how to transition to the new version. Also, we may notify you if changes are made to the existing version and we think you can benefit from knowing about these changes (such as a new useful field being added or data being updated).

We will retire older versions of methods only when we are completely sure that no one is using them.

Frontend and Backend Integrations

Crystal Roof API is suitable for integration with both frontend and backend due to its support for a high volume of requests per second.

CORS

By default, we set the 'Access-Control-Allow-Origin' response header to '*', indicating unrestricted usage. Please contact us if you would like to set a different value for this header. For example, you may want to specify a particular value if you plan to use our API directly from a web application.

Calls per second limit

Calls per second limit depends on the selected Crystal Roof API package. Please contact us at contact@crystalroof.co.uk and we will assist you in choosing the best package according to your requirements.

If you call the API too many times, exceeding your calls per second limit provided by the package, you will receive the 429 error status code (Too Many Requests). Please wait at least 500 ms before making a second attempt. You won't be charged for the requests with 429 error status code.

Caching Policy

When calling Crystal Roof API from the backend, there are no limitations on caching responses. If you call the API directly from the frontend, be aware that the cache time specified in the 'Cache-Control' response header is set to 10 minutes.

Data Coverage

The countries covered by specific API methods are displayed on the designated API method documentation pages.