└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # Skiddle Events Web API 2 | 3 | 4 | ## Getting Started 5 | 6 | The Skiddle Events API has been developed to follow RESTful principles where possible (and not overly complicated). The aim has been to create an API which is simple and intuitive to use rather than following strict policies to the letter. 7 | 8 | At present we don't have any client libraries available, but any REST library that allows you to specify the end-point can be used with this API. 9 | 10 | ### Return format 11 | 12 | All results are returned in plain-text JSON format which is cross-platform compatible. 13 | 14 | ### Authentication 15 | 16 | > All requests require a valid API key. For a free api key please [apply here](https://www.skiddle.com/api/join.php). 17 | 18 | To access the API you must specify your API KEY on all requests. This should be in the format 'api_key=abcdefghijklmnop' 19 | 20 | We monitor all requests and reserve the right to rate-limit or block any excessive requests. Limits are continually changed - please contact us if you are expecting to hit our API frequently. 21 | 22 | ### HTTPS 23 | 24 | All requests must be made over HTTPS (TLS v1.2+) 25 | 26 | --- 27 | 28 | ## Events 29 | 30 | Events search endpoint: **https://www.skiddle.com/api/v1/events/search/** (method: GET) Gets multiple events based upon search parameters (see below). 31 | 32 | > An example of a valid URL (returning gigs near Manchester City Centre) would be: https://www.skiddle.com/api/v1/events/search/?api_key=abcdefghijklmnop&latitude=53.4839&longitude=-2.2446&radius=5&eventcode=LIVE&order=distance&description=1 33 | 34 | Event details endpoint: **https://www.skiddle.com/api/v1/events/12345/** (method: GET) Gets information for a single event. 35 | 36 | 37 | ### Event search parameters 38 | 39 | #### GEOGRAPHICAL 40 | 41 | **latitude:** (decimal, optional) Specify a latitude to find nearby events (eg 53.000) 42 | 43 | **longitude:** (decimal, optional) Specify a longitude to find nearby events (eg -1.234) 44 | 45 | **radius:** (integer, optional) Find events within the specified miles radius (eg 10) 46 | 47 | **_To use geo searching, all 3 of the above parameters must be specified._** 48 | 49 | **country:** (string, optional) Find events within a certain country, using a specific ISO country code (eg GB) 50 | 51 | **getdistance:** (bool, optional) Return the distance from your specified location _(for this parameter to work, you must also provide a latitude and a longitude)_ 52 | 53 | 54 | #### EVENT FILTERS 55 | 56 | **keyword:** (string, optional) Search events using a keyword 57 | 58 | **eventcode:** (string, optional) Filter by type of event. Note the category is selected by the event promoter when submitting the event so can be subjective! Choose from: 59 | 60 | - FEST = Festivals 61 | - LIVE = Live music 62 | - CLUB = Clubbing/Dance music 63 | - DATE = Dating event 64 | - THEATRE = Theatre/Dance 65 | - COMEDY = Comedy 66 | - EXHIB = Exhibitions and Attractions 67 | - KIDS = Kids/Family event 68 | - BARPUB = Bar/Pub event 69 | - LGB = Gay/Lesbian event 70 | - SPORT = Sporting event 71 | - ARTS = The Arts 72 | 73 | 74 | **ticketsavailable:** (bool, optional) Find only events with tickets available to purchase 75 | 76 | **specialFeatured:** (bool, optional) Find events which are recommended by Skiddle 77 | 78 | **imagefilter:** (bool, optional) Find only events which have an image attached 79 | 80 | **description:** (bool, optional) Passing this parameter will mean that your results will contain artist and genre information for each event 81 | 82 | **under18:** (bool, optional) Find only events which under 18's are allowed to attend 83 | 84 | **minDate:** (string, optional) Find events on or after this date. Format as YYYY-MM-DD 85 | 86 | **maxDate:** (string, optional) Find events before or on this date. Format as YYYY-MM-DD 87 | 88 | **venueid:** (integer, optional) Find events at a particular venue. See the venues search for details. Can either be an integer, or a string of comma seperated integers (eg venueid=1,2,3) 89 | 90 | **b:** (integer, optional) Find events attached to a particular brandID (eg Ministry of Sound). See the brands search for details 91 | 92 | **a:** (integer, optional) Find events that a particular artistID is tagged to (eg Riva Starr). See the artsits search for details 93 | 94 | **g:** (integer, optional) Find events that a particular genreID is tagged to (eg Pop). Can either be an integer, or a string of comma separated integers (eg g=1,2,3) 95 | 96 | **order:** (string, optional) Specify sort order. Choose from: 97 | 98 | 99 | - date = will order by event date 100 | - bestselling = will order by bestselling events 101 | - trending = will return the events in trending order for the preceding week (default) 102 | - goingto = will order the events by the amount of people attending 103 | - distance = will return the events from closest to furthest from your specified location _(for this parameter to work, you must also provide a latitude and a longitude)_ 104 | 105 | 106 | **limit:** (integer, optional) Specify number of records returned (max 100, default 20) 107 | 108 | **shufflelimit:** (integer, optional) Used in conjunction with limit, API will retrieve {shufflelimit} events, randomise them, then return final {limit} events. This can be used to return a random subset of events that changes each time. 109 | 110 | **offset:** (integer, optional) Specify record number to start at (for paging, in conjunction with limit, order) (default 0) 111 | 112 | --- 113 | 114 | ## Venues 115 | 116 | Venues search endpoint: **https://www.skiddle.com/api/v1/venues/** (method: GET) Gets multiple venues based upon search parameters (see below) 117 | 118 | Venue details endpoint: **https://www.skiddle.com/api/v1/venues/12345/** (method: GET) Gets information for a single venue 119 | 120 | ### Venue search parameters 121 | 122 | #### GEOGRAPHICAL 123 | 124 | **latitude:** (decimal, optional) Specify a latitude to find nearby venues(eg 53.000) 125 | 126 | **longitude:** (decimal, optional) Specify a longitude to find nearby venues(eg -1.234) 127 | 128 | **radius:** (decimal, optional) Find venues within the specified miles radius (eg 10) 129 | 130 | **_To use geo searching, all 3 of the above parameters must be specified._** 131 | 132 | #### VENUE FILTERS 133 | 134 | **type:** (string, optional) Type of venue. Chose from: 135 | 136 | - B = Bar/Pub 137 | - N = Nightclub 138 | - L = Live Music 139 | - O = Outdoor venue 140 | - T = Theatre 141 | - S = Sports ground 142 | - G = Gallery 143 | 144 | **limit:** (integer, optional) Specify number of records returned (max 100, default 20) 145 | 146 | **offset:** (integer, optional) Specify record number to start at (for paging, in conjunction with limit, order) (default 0) 147 | 148 | --- 149 | 150 | ## Artists 151 | 152 | Artists search endpoint: **https://www.skiddle.com/api/v1/artists/** (method: GET) Gets multiple artists based upon search parameters (see below) 153 | 154 | ### Artist search parameters 155 | 156 | **name:** (string, optional) Name of artist to search for 157 | 158 | **venueid:** (integer, optional) Find artists playing at a particular venue. See the venues search for details (as an integer) 159 | 160 | **b:** (integer, optional) Find artists playing for a particular brandID (eg Ministry of Sound). See the brands search for details 161 | --------------------------------------------------------------------------------