Welcome to Swiftcomplete 👋

Our APIs are simple to use and easy to integrate. We’ve created a short integration guide to answer common questions and to help you design the best possible integration.

Please read this guide thoroughly before starting your integration to avoid any future issues, and to make the best possible use of the service.

Keep up to date with the latest improvements, new technology and updates

Get in touchFollow us

Best Practice

Our API is designed to be reliable and robust, and we aim to mitigate issues which could cause the API to become inaccessible, with advanced monitoring, alerting and redundant resources.

However, it’s possible that problems may occur outside of our control, and so we have best practices which we require our customers to follow to minimise the impact of any updates or short-lived service disruption.

Handle Unexpected Problems Gracefully

Design your implementation so that your website or product still functions if the Swiftcomplete API is inaccessible or is responding slowly.

Example

You’re an online estate agent who uses our Summarise API to pre-populate property listings with information about the local area.

Rather than preventing users from creating new listings if the API is unavailable, allow users to create listings manually instead.

Don’t prevent your site from working because of temporary issues with the Swiftcomplete API.

Don’t Split, Parse or Interpret Text Within Responses

Any information that is returned, including text and IDs, are liable to change at any point without notice, as we make improvements and add functionality to the service.

Example

The Swiftcomplete API returns the string:

{ motorway: “Motorway Junctions: M1 J25 is the closest junction (1 mile)” }

Don’t attempt to split the string on ‘:’ to get the name of the motorway. The format of any string can and will change frequently, at any point, without notice.

You must use the whole string as it is returned.

Speak to us if you require additional information from the API, and we may be able to provide it in a more sustainable way.

Don’t rely on the order of Objects, Fields or Properties

The order of properties can change at any time. You should design your system in a way that can cope with properties being returned in different orders, even between requests.

Example

The Swiftcomplete API returns the response:

{
      motorway: “xxxxxxx”,
      station: “xxxxxxx”,
      randomOtherField: “xxxxxxx”
}

This could equally be returned as:

{
      randomOtherField: “xxxxxxx”,
      station: “xxxxxxx”,
      motorway: “xxxxxxx”
}

Station and motorway can be returned in any order. Don’t expect motorway to always be first.

Using the API

Calling the API

The Swiftcomplete API is accessible only via HTTPS, and uses the base URL:

https://api.swiftcomplete.com/v1/

Each API endpoint returns JSON. Parameters in the query string must be URL encoded.

Versioning

We continuously release compatible changes, data updates and feature additions / improvements without changing the version of the API. If a change is not backwards-compatible, we update the version number.

If we update the version number of the API, we may need to retire older versions of the API. If this happens, we will provide you with advance notice and provide upgrade instructions - these kinds of changes are a rare and infrequent occurrence.

Authentication

Your Swiftcomplete API key is required to authenticate every request. Your API key can either be provided as a URL parameter, or as a HTTP header.

It can be useful to use the key as a URL parameter during development, and to move to a HTTP header for production.

As a URL parameter (key=XXXXX)

https://api.swiftcomplete.com/v1/?key=XXXXXXXXXXXX

As a HTTP header

Header name: key

Header value: Your key

API Endpoints

Summarise API

/search/summariseGET

The summarise API uses our AI, geocoding and natural language technology to automatically generate a summary description of a location, item, event etc.

You can use as many or few optional parameters as you like. Simply providing the postcode generates a useful summary, and providing more information will produce a more detailed response.

Parameters

  • summaryTypeRequired

    The type of summary to be generated.

    Accepted values

    • propertyListing

      Generates a property listing. RequiressummaryLocationCentrePoint, also accepts anyproperty*parameter to generate a more detailed description.

  • summaryLocationCentrePointRequired for location summary

    The centre point to be described. For example, a property location to create a summary about a property for sale, or a store postcode to create a summary about a store's location.

    Accepted values

    • GB Postcode

      e.g. NG1 1EQ

    • WGS84 latitude,longitude

      e.g. 52.955768, -1.142841

  • propertyAttachmentOptional

    How the property is attached (if at all). Not suitable for flats / apartments.

    Accepted values

    • Detached
    • Semi detached
    • Terrace
    • Mid terrace
    • End terrace

  • propertyAvailabilityOptional

    The basis on which the property is available (e.g. to purchase or to rent)

    Accepted values

    • Sale
    • Rent

  • propertyBedroomsOptional

    Number of bedrooms in the property.

    Accepted values

    • Integer between 1 & 30

  • propertyEraOptional

    The era of the property

    Accepted values

    • Georgian
    • Victorian
    • Edwardian
    • Period
    • Modern
    • New Build

  • propertyFloorOptional

    If this property is a flat / apartment, the floor that the property is on.

    -1 = basement, 0 = ground, 1 = first, 2 = second etc.

    Accepted values

    • Integer between -1 & 100

  • propertyPriceOptional

    The price of the property to buy or rent, e.g. 145000 or 850

    Accepted values

    • Float >= 0.0

  • propertyPriceTypeOptional

    The type of price, e.g. asking price, PCM etc.

    Accepted values

    • If propertyAvailability is sale:
    • askingPrice
    • guidePrice
    • offersRegion
    • offersOver
    • If propertyAvailability is rent:
    • pcm
    • pw

  • propertyTypeOptional

    The type of the property

    Accepted values

    • Apartment
    • Bungalow
    • Cottage
    • Flat
    • House
    • Maisonette
    • Studio Flat

  • providerNameOptional

    If you're describing an item for sale, this can be used to say who is providing it.

    Accepted values

    • String, 1-100 chars

      e.g. Swiftcomplete Estate Agents

Response

Example response

  {
  "data":
          {
          "text":
              [
                  {
                      "type": "briefDescriptionBullets",
                      "displayType": "list",
                      "title": "In brief",
                      "lines":
                              [
                                  {
                                      "type": "location",
                                      "text": "Nottingham city centre location"
                                  },
                                  {
                                      "type": "propertyBedrooms",
                                      "text": "3 bedrooms"
                                  }
                              ]
                  },
                  {
                      "type": "fullDescription",
                      "displayType": "text",
                      "title": "Full description",
                      "lines":
                              [
                                  {
                                      "type": "",
                                      "text": "Located in Nottingham city centre, this 3 bedroom detached property is conveniently situated around 4.5 miles from M1 motorway junction 26 and less than a mile from Nottingham Station."
                                  }
                              ]
                  }
              ]
          }
  }

Parsing the response

data.text is an array of blocks, which will be empty if there were no matches. Each block contains the following fields:

  • type

    An enum to determine the type of the block of text. Can be used to programatically include / exclude blocks of text.

    Note: Responses will not always return all types (if they are blank for example) - it's important to check for the existence of a type and not to assume that it will be there.

    Example values

    • briefDescriptionBullets
    • fullDescription
    • locationDescription

  • displayType

    An enum to help you determine how to display thelines

    Possible values

    • list

      Each line is a bullet point

    • text

      Each line is a paragraph

  • title

    Display friendly text which can be used as a header for this 'block'

  • lines

    An array of display lines. You can determine whether these are paragraphs or bullet points by checkingdisplayType

    Each line contains the following fields:

    • type

      Sometimes blank. Can be used to identify the type of line if present

    • text

      The text to display

Using the response

Here's some example javascript to loop through the response and generate HTML to be inserted into a div with ID 'result':

var resultDiv = document.getElementById('result');
var outputStr = '';

for (var i = 0; i < data.text.length; i++) {
    outputStr += '<h3>' + data.text[i].title + '</h3>';

    switch (data.text[i].displayType) {
        case 'list':
            outputStr += '<ul>';

            for (var j = 0; j < data.text[i].lines.length; j++) {
                outputStr += '<li>' + data.text[i].lines[j].text + '</li>';
            }

            outputStr += '</ul>';
            break;
        case 'text':
            for (var j = 0; j < data.text[i].lines.length; j++) {
                outputStr += '<p>' + data.text[i].lines[j].text + '</p>';
            }
            break;
    }
}

resultDiv.innerHTML = outputStr;

Handling errors

Successful requests return HTTP status 200. Any other HTTP status indicates an error, and should be handled accordingly.

If a request can't be processed for any reason, a HTTP status code and error text description will be returned:

HTTP Status: 400
JSON response:
{
   "error": "Error description goes here"
}

Specific HTTP codes returned by this endpoint:

(More error codes may be returned in future. Treat anything other than 200 as an error)

  • 200

    Your request was processed successfully. If the summaryLocationCentrePoint wasn't recognised, the results will be empty.

  • 400

    A required parameter is missing, or a parameter has been provided with an invalid value

  • 401

    Your API key is either missing or invalid

  • 429

    Too many requests. You have sent too many requests in a short space of time, and have reached your rate limit.

  • 500

    An internal error occurred. Try again later

  • 503

    The API is currently unavailable - this is typically a short-lived problem. Try again later

Example request

  • Describing a 3 bed detached house at postcode NG1 1EQ being sold by Swiftcomplete Estate Agents:

    https://api.swiftcomplete.com/v1/search/summarise?key=INSERTKEYHERE&summaryType=propertyListing&summaryLocationCentrePoint=NG11EQ&propertyAttachment=detached&propertyBedrooms=3&providerName=Swiftcomplete Estate Agents

Follow us & keep in touch:

© 2019 Swiftcomplete Ltd - All rights reserved. Company registration number 11211428, VAT registration number GB 293 1456 91