Widgety API
1.0
11
API Server
Verification passed! You now have access to the Integration pages. Verification failed!

Introduction

Welcome to the Widgety API!

You can use our API to get content from Widgety's content-sharing platform and seamlessly integrate it into your products.

Samples are available for JSON and XML endpoints in the dark area to the right.

Authentication

Example Request

https://www.widgety.co.uk/api/operators.json?app_id=<key>&token=<token>
https://www.widgety.co.uk/api/operators.xml?app_id=<key>&token=<token>

Make sure to replace <key> with your API key and <token> with your application token.

You must have an application ID and application token to query the API. If you do not have an application ID and application token, you must contact us to assign you one. Please email damian@widgety.co.uk with some information about your company, as well as your contact details.

Once an app has been assigned to you, you'll be able to access it by following the steps below:

  1. Sign into Widgety at https://www.widgety.co.uk
  2. Navigate to the My APP Keys section via the navbar

Making API Requests

API BASE URL https://www.widgety.co.uk/api/

Requests to the API must be made over HTTPS. Any HTTP requests are met with a HTTP 302 to its HTTPS equivalent.

Request to the API can be returned in either JSON format or XML format. This is selected by appending the query string with the required format.

EXAMPLE JSON URL QUERY STRING https://www.widgety.co.uk/api/ships.json

EXAMPLE XML URL QUERY STRING https://www.widgety.co.uk/api/ships.xml

Paging

Requests made to the API that retrieve lists of objects such as Operators or Ships can be paginated.

The number of returned objects per page is set by adding the 'limit' argument to the query string.

The page requested is set by adding the 'page' argument to the query string.

Example Request

https://www.widgety.co.uk/api/operators.json?app_id=<key>&token=<token>?&limit=<limit>&page=<page>
https://www.widgety.co.uk/api/operators.xml?app_id=<key>&token=<token>?&limit=<limit>&page=<page>
Attribute Type Value
limit int by default, this value is set to 25
page int the page requested

Images

Example Request

https://www.widgety.co.uk/api/places/burley-golf-club.json?token=33ab2c8e1e35f880c24f66598497194c03dd7cdaf322ba08031992b80d5b786b&app_id=00fe59f4ae6d8012f3b4eeb3fe849c20c6db78b9&compression%5Ballow_lossy%5D=false&compression%5Bjpegoptim%5D%5Ballow_lossy%5D=false&compression%5Bjpegoptim%5D%5Bmax_quality%5D=65&cover_image_geometry%5B%5D=200x200&cover_image_geometry%5B%5D=1000x1000&profile_image_geometry=300x300#

{
    "title": "Burley Golf Club",
    "description": "<p>Visitors are always assured of a warm welcome at Burley Golf Club, in the heart of the New Forest National Park, Hampshire.  There is an abundance of wildlife and splendid views to enjoy whilst playing the course.  As Burley is a 9 hole course, it is advisable to check availability with the Secretary’s office.  When arriving at Burley, visitors must register before play to obtain the green fee ticket. Play is from the Yellow tees for gentlemen and Red tees for Ladies.</p>",
    "telephone": "01425 402431",
    "email": "hello@burleygolfclub.co.uk",
    "video_url": "",
    "twitter_url": "",
    "facebook_url": "T",
    "id": "burley-golf-club",
    "website_url": "",
    "category": "Golf Club",
    "profile_image_href": "//www.widgety.co.uk/media/W1siZiIsIjIwMTUvMTEvMjAvMDkvMTgvMzUvODMvQnVybGV5X2dvbGZfY2x1Yl9sb2dvLnBuZyJdLFsicCIsInRodW1iIiwiMzAweDMwMCJdLFsicCIsImNvbXByZXNzIix7ImFsbG93X2xvc3N5IjoiZmFsc2UiLCJqcGVnb3B0aW0iOnsiYWxsb3dfbG9zc3kiOiJmYWxzZSIsIm1heF9xdWFsaXR5IjoiNjUifX1dXQ/Burley%20golf%20club%20logo.png?sha=f0a5b02e1cd7478f",
    "cover_image_href": {
        "200x200": "//www.widgety.co.uk/media/W1siZiIsIjIwMTUvMTEvMjAvMDkvMTgvNDAvNzIxL0J1cmxleV9Hb2xkX2NsdWJfY292ZXIuanBnIl0sWyJwIiwidGh1bWIiLCIyMDB4MjAwIl0sWyJwIiwiY29tcHJlc3MiLHsiYWxsb3dfbG9zc3kiOiJmYWxzZSIsImpwZWdvcHRpbSI6eyJhbGxvd19sb3NzeSI6ImZhbHNlIiwibWF4X3F1YWxpdHkiOiI2NSJ9fV1d/Burley%20Gold%20club%20cover.jpg?sha=5152716344c2f562",
        "1000x1000": "//www.widgety.co.uk/media/W1siZiIsIjIwMTUvMTEvMjAvMDkvMTgvNDAvNzIxL0J1cmxleV9Hb2xkX2NsdWJfY292ZXIuanBnIl0sWyJwIiwidGh1bWIiLCIxMDAweDEwMDAiXSxbInAiLCJjb21wcmVzcyIseyJhbGxvd19sb3NzeSI6ImZhbHNlIiwianBlZ29wdGltIjp7ImFsbG93X2xvc3N5IjoiZmFsc2UiLCJtYXhfcXVhbGl0eSI6IjY1In19XV0/Burley%20Gold%20club%20cover.jpg?sha=509fcf242a08747b"
    },
    "html_href": "https://www.widgety.co.uk/places/burley-golf-club",
    "attachments": [],
    "country_code": "GB",
    "county_state": "Hampshire",
    "street_address": "Cott Lane,",
    "town_city": "Burley",
    "postcode": "BH24 4BB",
    "longitude": "-1.689055",
    "latitude": "50.824743",
    "opening_hours": ""
}

Geometry

You may specify cover_image_geometry and profile_image_geometry for ships, promotions, events, operators and places. Geometry string examples can be found here

You may also set this parameters for specific model only e.g. place_cover_image_geometry. This is useful for nested resources. If model specific param is not set general params (cover_image_geometry and profile_image_geometry) will be applied.

For Ships you may also set images_geometry which is general for all additional ship sections such as deckplans and dinning options. And you can use model specific params such as uniq_feature_images_geometry and entertainment_type_images_geometry

Should you need the same image(s) in different sizes, you can pass arrays of geometry strings. In this case they will look like images_geometry[]=1000x100#&images_geometry[]=200x200ne and response will contain map with geometries and image links. See example response on the right side of screen (e.g. accommodation types section).

Compression

It's also possible to specify compression settings in the same way as for geometry e.g. compression, profile_image_compression, place_profile_image_compression. Also you can set place_images_compression or global images_compression for additional images such as deckplans and attachments_compression for attachments' thumbnails.

Example in the right section will apply jpegoptim tool with lossy compression allowed and max quality set to 65%. We support many image optimisation tools (workers), which are listed below. For more information please visit image_optim repo.

Options

Worker can be disabled by passing false instead of options hash or by setting option :disable to true.

advpng:
  • :level — Compression level: 0 - don't compress, 1 - fast, 2 - normal, 3 - extra, 4 - extreme (defaults to 4)
gifsicle:
  • :interlace — Interlace: true - interlace on, false - interlace off, nil - as is in original image (defaults to running two instances, one with interlace off and one with on)
  • :level — Compression level: 1 - light and fast, 2 - normal, 3 - heavy (slower) (defaults to 3)
  • :careful — Avoid bugs with some software (defaults to false)
jhead:

Worker has no options (just pass true to enable)

jpegoptim:
  • :allow_lossy — Allow limiting maximum quality (defaults to false)
  • :strip — List of extra markers to strip: :comments, :exif, :iptc, :icc or :all (defaults to :all)
  • :max_quality — Maximum image quality factor 0..100, ignored in default/lossless mode (defaults to 100)
jpegrecompress:
  • :allow_lossy — Allow worker, it is always lossy (defaults to false)
  • :quality — JPEG quality preset: 0 - low, 1 - medium, 2 - high, 3 - veryhigh (defaults to 3)
jpegtran:
  • :copy_chunks — Copy all chunks (defaults to false)
  • :progressive — Create progressive JPEG file (defaults to true)
  • :jpegrescan — Use jpegtran through jpegrescan, ignore progressive option (defaults to false)
optipng:
  • :level — Optimization level preset: 0 is least, 7 is best (defaults to 6)
  • :interlace — Interlace: true - interlace on, false - interlace off, nil - as is in original image (defaults to false)
  • :strip — Remove all auxiliary chunks (defaults to true)
pngcrush:
  • :chunks — List of chunks to remove or :alla - all except tRNS/transparency or :allb - all except tRNS and gAMA/gamma (defaults to :alla)
  • :fix — Fix otherwise fatal conditions such as bad CRCs (defaults to false)
  • :brute — Brute force try all methods, very time-consuming and generally not worthwhile (defaults to false)
  • :blacken — Blacken fully transparent pixels (defaults to true)
pngout:
  • :copy_chunks — Copy optional chunks (defaults to false)
  • :strategy — Strategy: 0 - xtreme, 1 - intense, 2 - longest Match, 3 - huffman Only, 4 - uncompressed (defaults to 0)
pngquant:
  • :allow_lossy — Allow quality option (defaults to false)
  • :max_colors — Maximum number of colors to use (defaults to 256)
  • :quality — min..max - don't save below min, use less colors below max (both in range 0..100; ignored in default/lossless mode (defaults to 100..100, 0..100 in lossy mode)
  • :speed — speed/quality trade-off: 1 - slow, 3 - default, 11 - fast & rough (defaults to 3)
svgo:
  • :disable_plugins — List of plugins to disable (defaults to [])
  • :enable_plugins — List of plugins to enable (defaults to [])

Image URLs

To avoid creating unnecessary files on our Amazon Web Server, each image created using a specific set of geometry/compression will first be provided as a relative link. Once this link has been loaded once, the image will have been generated, and the request will return a proper AWS link from that point on.

Please note that you may find that some images will already been generated. This means that a previous user already requested the same geometry/compression for this image and that the file already exists on our Amazon Web Server.

operators

2
GET

operators/get

REFERENCE

Get all information about concrete operator.

PARAMETERS
:id string

valid operator slug american-cruise-lines

/
operators
/
:id
Request
Response
200
BODY
GET

operators/get_all

REFERENCE

Making a request for Operators filters can be used to narrow down the returned number of Operators. The filter is set by adding the attribute to be filtered by as an argument to the query string.

PARAMETERS
start_from string

filter by name of port where operator's cruises start.

visit_port string

filter by name of port visited by operator's cruises.

/
operators
Request
Response
200
BODY

ships

2
GET

ships/get_all

REFERENCE

Retrieve all ships

PARAMETERS
size enumerated

filter by size

boutique

Boutique (under 249)

small

Small (250 - 749)

medium

Medium (750 - 1748)

large

Large (above 1750)

style enumerated

filter by style

classic

Classic

expedition

Expedition

resort

Resort

premium

Premium

premium_resort

Premium Resort

luxury

Luxury

ultra_luxury

Ultra Luxury

type enumerated

filter by type

ocean

Ocean

river

River

ferry

Ferry

language enumerated

filter by language

en

English

en-GB

English (British)

en-US

English (American)

en-AU

English (Australian)

fr

French

fr-CA

French (Canadian)

fr+en

French & English

de

German

de+en

German & English

it

Italian

it+en

Italian & English

no

Norwegian

no+en

Norwegian & English

es

Spanish

es+en

Spanish & English

none

No official language

varies

Varies depending on itinerary

currency enumerated

filter by currency

USD

US Dollar ($)

GBP

Pound Sterling (£)

EUR

Euro (€)

AUS

Australian Dollar ($)

JPY

Japanese Yen (¥)

CNY

Chinese Yuan (¥)

NOK

Norwegian Krone (kr)

smoking enumerated

filter by smoking options

smoking_permitted

Yes

none

No

some

Designated areas only

balcony

Balcony only

e-cig

E-cigarette only

balcony_cabins

Balcony, cabins & designated areas

cabins_designated

Select cabins & designated areas only

dining_experience enumerated

filter by dinning experience

complimentary

Complimentary

cover

Cover charge may apply

snacks

Snacks/ light bites

adults_only enumerated

filter by adults only options

adults_only

Yes

kids_allowed

No

itinerary_dependent

Itinerary dependent

no_kids

Children not advised

kids enumerated

filter by kid facilities

available

Yes

none

No

itinerary_dependent

Itinerary dependent

nursery enumerated

filter by nursery

nursery

Nursery

in_cabin_only

In cabin only

cabin_and_nursery

In cabin and nursery

babysitting

Babysitting

none

Not available

operator string

valid operator slug american-cruise-lines

start_from date_time

filter by name of port where ship's cruises start.

visit_port string

filter by name of visited ports

launch_min integer

filter by launch year. Range start

launch_max integer

filter by launch year. Range end

refit_min integer

filter by refit year. Range start

refit_max integer

filter by refit year. Range end

capacity_min integer

filter by capacity. Range start

capacity_max integer

filter by capacity. Range end

crew_min integer

filter by crew. Range start

crew_max integer

filter by crew. Range end

tonnage_min integer

filter by tonnage. Range start

tonnage_max integer

filter by tonnage. Range end

length_min integer

filter by length. Range start

length_max integer

filter by length. Range end

width_min integer

filter by width. Range start

width_max integer

filter by width. Range end

cabins_min integer

filter by cabins number. Range start

cabins_max integer

filter by cabins number. Range end

large_cabins_min integer

filter by large cabins number. Range start

large_cabins_max integer

filter by large cabins number. Range end

wheelchair_cabins_min integer

filter by wheelchair cabins number. Range start

wheelchair_cabins_max integer

filter by wheelchair cabins number. Range end

include_cruises boolean

include the cruises section of the results

/
ships
Request
Response
200
BODY
GET

ships/get

REFERENCE

Get all information about concrete ship.

PARAMETERS
:slug string

slug of the ship page

include_cruises boolean

include the cruises section of the results

/
ships
/
:slug
Request
Response
200
BODY

cruises

2

Version 2

You can switch to Widgety API version 2 by adding api_version=2 to Accept HTTP header. So it will look like Accept: application/json;api_version=2

GET

cruises/get_all

REFERENCE

Making a request for Cruises filters can be used to narrow down the returned number of Cruises. The filter is set by adding the attribute to be filtered by as an argument to the query string.

PARAMETERS
start_from string

filter by name of port where cruise starts.

visit_port string

filter by name of visited ports

operator string

filter by Operator ids

length integer

filter by vacation days number

start_date_range_beginning date_time

find cruises with start date greater or equal that date specified

start_date_range_end date_time

find cruises with start date less or equal that date specified

ship_name string

filter by name of ship, non-case sensitive

charter string

false by default. Pass true or 1 if you want to get only charter cruises and false or 0 to get all except charter ones. Set to any to get all cruises.

cruise_type enumerated

filter by type

ocean

Ocean cruises

river

River cruises

s string

set sort order e.g. 'starts_on asc'

/
cruises
Request
Response
200
BODY
GET

cruises/get

REFERENCE

Get all information about concrete cruise.

PARAMETERS
:ref string

cruise id

/
cruises
/
:ref
Request
Response
200
BODY
GET

cruises/port_visits

REFERENCE

This endpoint retrieves port visits for a specific cruise.

PARAMETERS
:ref string

cruise id

/
cruises
/
:ref
/
port_visits
Request
Response
200
BODY

Version 1 (legacy)

Though the Version 1 of the API is still supported, it will not benefit from any new features released in the future. Should you still be using Version 1 and wish to upgrade to Version 2, please contact support@widgety.co.uk.

GET

cruises/get_all

REFERENCE

Making a request for Cruises filters can be used to narrow down the returned number of Cruises. The filter is set by adding the attribute to be filtered by as an argument to the query string.

PARAMETERS
start_from string

filter by name of port where cruise starts.

visit_port string

filter by name of visited ports

operator string

filter by Operator ids

length integer

filter by vacation days number

start_date_range_beginning date_time

find cruises with start date greater or equal that date specified

start_date_range_end date_time

find cruises with start date less or equal that date specified

ship_name string

filter by name of ship, non-case sensitive

region string

filter by cruise region, non-case sensitive

charter string

false by default. Pass true or 1 if you want to get only charter cruises and false or 0 to get all except charter ones. Set to any to get all cruises.

cruise_type enumerated

filter by type

ocean

Ocean cruises

river

River cruises

s string

set sort order e.g. 'starts_on asc'

/
cruises
Request
Response
200
BODY
GET

cruises/get

REFERENCE

Get all information about concrete cruise.

PARAMETERS
:ref string

cruise id

/
cruises
/
:ref
Request
Response
200
BODY
GET

cruises/port_visits

REFERENCE

This endpoint retrieves port visits for a specific cruise.

PARAMETERS
:ref string

cruise id

/
cruises
/
:ref
/
port_visits
Request
Response
200
BODY

ports

2
GET

ports/get

REFERENCE

Get all information about concrete port

PARAMETERS
:unlocode string

port UNLOCODE

/
ports
/
:unlocode
Request
Response
200
BODY
GET

ports/get_all

REFERENCE

returns list of ports

PARAMETERS
/
ports
Request
Response
200
BODY

places

3
GET

places/get

REFERENCE

This endpoint retrieves specified Place.

PARAMETERS
:id string

place id

past boolean

filters associated expired events & promotions (end_at in the past)

current boolean

filters associated valid published events & promotions (publish_at in the past + end_at is in the future)

future boolean

filters associated future events & promotions (publish_at is in the future)

/
places
/
:id
Request
Response
200
BODY
GET

places/get_all

REFERENCE

This endpoint retrieves all Places.

PARAMETERS
/
places
Request
Response
200
BODY
GET

places/batch

REFERENCE

This endpoint retrieves all specified Places.

PARAMETERS
ids array

place ids. Pass as array (ids[]=) or as comma-separated string

/
places_batch
Request
Response
200
BODY