LairOut API

Authentication

To authenticate with LairOut API, you have to sign up with your user or create an account.
Once you are logged in LairOut, go under your user settings, and at the bottom of the page click 'Enable API'.
This will generate an authentication token (API authentication); on that page you will also have to fill in the website URL that you will use to display or insert events from.
LairOut API Terms of Service are available here: Terms of Service

Each API transaction is logged on LairOut system.
You can review your transaction on this page: API Transactions

End points

• https://www.lairout.com/api/1/events.xml
• https://www.lairout.com/api/1/events.json
• https://www.lairout.com/api/1/events.json?callback=someFunction

The response format is based on the dot extension format. There are three possible response formats:

• XML
• JSON
• JSONP (if a callback parameter is specified)

Function Reference

Action	End Point	HTTP method
Download Events	/api/1/events.xml	GET
Upload Events	/api/1/events.xml	POST
Delete Events	/api/1/events.xml	DELETE

HTTP Response Codes

• 200 - Success
• 400 - Error - see string returned for details
• 401 - Unathorized
• 404 - Request not found
• 500 - Server error - we will be notified and we'll look into the problem as soon as possible

Download Events

End point "/api/1/events.xml", HTTP method GET.
The result events are ordered by start date; the first event starting will be the first one returned.
Note: the API only returns current events, past events are not available using the API.

Requested Parameters

• token, string, used for authentication, required: YES
• locality, string, locality of interest, required: YES if other locality parameters are not provided; ex: milan italy
• latitude, float, latitude of the locality, required: YES if other locality parameters are not provided; ex: 83,1233123
• longitude, float, longitude of locality, required: YES if other locality parameters are not provided; ex: 83,1233123
• distance, float (kms), distance for latitude and longitude point specified,required: YES if latitude and longitude are provided; ex: 10
• bbox, string, bounding box of locality of interest (lat lon in this order: SW NE - south west / north east), required: YES if other locality parameters are not provided; ex: 40.329795743702064,-75.4815673828125,41.089702205437405,-72.52899169921875
• start_date, date, start date of the events, required: NO, ex: 01/01/2015
• end_date, date, end date of the events, required: NO; ex: 01/06/2016
• category, string, category of events, required: NO; ex: Concert
• limit, integer, number of events to return, required: NO; ex: 8
• user_id, integer, events created by a particular user, required: NO, ex: 23

Example of request: https://www.lairout.com/api/1/events.json?token=TOKEN&locality=wellington%20new%20zealand

Locality, latitude, longitude, distance and bbox parameters

You will need to provide at least one of these combination:

1. locality (first precedence) - coordinates will be calculated using an external webservice, it is the slower option available (external webservice lookup)
2. latitude, longitude, distance - coordinates will be calculated using the point of the coordinates specified, plus the distance in kilometers
3. bbox - you specify the bounding box, nothing is dynamically calculated; lat lon in this order: SW NE - south west / north east

Start date, End date

You can filter by start date and end date. If not provided, start date will be the current date, and end date will be 1 month from the start date.

Category

This is the list of available categories:

1. Music
2. Art
3. Cultural
4. Other

User id

User id of the creator of the event. You can check your user id under your api settings page.

Limit

You can specify the number of events to be returned: minimun is 1, maximum is 10; the default is 10.

Response

• id: LairOut system id of the event
• url: LairOut url of the event (must be displayed as stated on the Terms of Service of the API)
• category: category of the event
• name: name of the event
• address: text/description of the address (not the coordinates)
• latitude: coordinate
• longitude: coordinate
• description: description of the event. It will be truncated to 150 characters if longer than that
• starts_on: start time and date of the event
• ends_on: ebd time and date of the event
• photo: if present, the url of the photo
• small_photo: if present, the url of the smaller version of the photo

Example:

<?xml version="1.0" encoding="UTF-8"?>
<events type="array">
  <event>
    <description>description...</description>
    <url>http://www.lairout.com/events/10</url>
    <starts-on>27 Feb 2013, 08:50pm</starts-on>
    <ends-on>06 Mar 2013, 08:50pm</ends-on>
    <photo></photo>
    <small-photo></small-photo>
    <id type="integer">10</id>
    <category>Concert</category>
    <name>one</name>
    <address>address</address>
    <latitude type="float">-41.2858276</latitude>
    <longitude type="float">174.7297211</longitude>
  </event>
  <event>
    <description>description</description>
    <url>http://www.lairout.com/events/11</url>
    <starts-on>27 Feb 2013, 08:50pm</starts-on>
    <ends-on>06 Mar 2013, 08:50pm</ends-on>
    <photo></photo>
    <small-photo></small-photo>
    <id type="integer">11</id>
    <category>FLASH MOB</category>
    <name>name event</name>
    <address>somehwre</address>
    <latitude type="float">-41.2858276</latitude>
    <longitude type="float">174.7297211</longitude>
  </event>
</events>

Upload/Update Events

End point "/api/1/events.xml" , HTTP method POST, Content Type: application/xml
Be aware that you cannot upload more than 10 events per HTTP call, otherwise an error will be returned.
Note: you can only upload current or future events, the API does not allow to upload past events.

Requested Parameters

• token, string, used for authentication, required: YES
• name, string, name of the event, required: YES, max 255 characters
• category, string, category of events, required: NO; ex: Concert
• starts_on, date, start date of the events, required: YES, ex: 01/01/2015
• ends_on, date, end date of the events, required: YES; ex: 01/06/2016
• address, string, address of the event, required: YES
• description, string, description of the event, required: NO
• latitude, float, latitude of the locality, required: YES if it cannot be calculated from the provided address; ex: 83,1233123
• longitude, float, longitude of locality, required: YES if it cannot be calculated from the provided address; ex: 83,1233123
• image, string, base64 encoded image, required: NO
• reference, string, a unique string that allows you to control your uploaded events, required: NO; max 255 characters

Additional parameters for recurring events:

• serie, required: NO
• ends_on, date, end date of the serie of events, required: YES (if serie is specified); ex: 01/06/2016
• frequency, string, frequency of the recurring event, required: YES (if serie is specified); ex: monthly

Category

This is the list of available categories:

1. Music
2. Art
3. Cultural
4. Other

Start date, End date

You can only upload current or future events.
Different categories have different duration limitations. If the event is out of range, you will receive a validation error in the response.

Address, Latitude, Longitude

The address where the event will occur.
If you do not provide latitude and longitude, those will be calculated by the provided address using an external webservice. If the coordinates cannot be calculated, you will receive a validation error and you will have to provide the coordinates manually.

Description

Long description of the event. It doesn't have any restriction in terms of length/number of characters.

Reference

A string or an unique reference that you might want to specify to identify your events uploaded on LairOut.
This field is not compolsury, but we recommend you set.
If you upload twice the event with this same reference, the event will be updated.
Also this reference allows you to delete events if you have to.
We strongly recommend that you set this parameter.

Serie

If serie is specified, the event will be marked as recurring, and all recurring events will be created.
The response will include all the events created for the serie.
Serie takes 2 parameters: ends_on and frequency.
The list of supported frequency is the follow:

1. Weekly
2. Fortnightly
3. Monthly
4. Every 3 Months
5. Every 6 Months
6. Yearly

Example of request:

<?xml version="1.0"?>
<events>
  <event>
    <name>Api 1</name>
    <category>conference</category>
    <starts_on>01/01/2016</starts_on>
    <ends_on>05/01/2016</ends_on>
    <description>Api 1</description>
    <address>via test germany</address>
    <serie>
      <frequency>yearly</frequency>
      <ends_on>01/01/2020</ends_on>
    </serie>
  </event>
</events>

Response

• id: LairOut system id of the event; if it is set, the event had a validation error; check the errors field for details.
• url: LairOut url of the event (must be displayed as stated on the Terms of Service of the API)
• category: category of the event
• name: name of the event
• address: text/description of the address (not the coordinates)
• latitude: coordinate
• longitude: coordinate
• description: description of the event. It will be truncated to 150 characters if longer than that
• starts_on: start time and date of the event
• ends_on: ebd time and date of the event
• photo: if present, the url of the photo
• small_photo: if present, the url of the smaller version of the photo
• reference: if present, the reference you specified for the event
• errors: if present, the error that stopped the event to be saved
• serie_id: if present, the serie id of the event, confirming that the event has been created as recurring
• api-transaction-id: system id of the transaction

Example:

<?xml version="1.0" encoding="UTF-8"?>
<events type="array">
<event>   
<description>Api description</description>
<url>http://www.lairout.com/events/12</url>
<starts-on>21 Feb 2013, 08:43am</starts-on>
<ends-on>28 Feb 2013, 08:43am</ends-on>
<photo></photo>
<small-photo></small-photo>
<id type="integer">12</id>
<category>Conference</category>
<name>Api 1</name>
<address>test street germany</address>
<latitude type="float">45.70572621000001</latitude>
<longitude type="float">9.686958250000002</longitude>
<serie-id type="integer">19</serie-id>
<api-transaction-id type="integer">69</api-transaction-id>
<errors type="array"/>
<reference>my reference</reference>
</event>
</events>

Delete Events

End point "/api/1/events.xml", HTTP method DELETE, Content Type: application/xml
Be aware that you cannot delete more than 10 events per HTTP call, otherwise an error will be returned.
Note: you can only delete current or future events, the API does not allow to delete past events.

Requested Parameters

• reference, string, a unique string that allows you to control your events, required: YES; max 255 characters

Reference

A string or an unique reference that you might want to specify to identify your events uploaded on LairOut.

Example of request:

<?xml version="1.0"?>
<events>
  <event>
    <reference>my reference</reference>
  </event>
</events>

Response

• reference: the previous reference of the event just deleted

Example:

<?xml version="1.0" encoding="UTF-8"?>
<events type="array">
<event>   
<reference>my reference</reference>
</event>
</events>

LairOut Map Widget

The map widget allows you to 'iframe' LairOut map with locality specified and some extra parameters (start date and end date of the events).
You can click the top right controller on the map on the home page to try out the simple version of the widget; the url generated reflects the actual bounding box of the map and the date filters.
The widget offers also extra more advanced options, explained here (see sections below).

<iframe width="425" height="350" frameborder="0" scrolling="no" marginheight="0" marginwidth="0" src="http://www.lairout.com/embed/?bbox=40.14318974292438,-75.135498046875,41.261291493919884,-72.18292236328125&starts_on=07-02-2013&ends_on=08-03-2013"></iframe><br/><small><a href="http://www.lairout.com" style="color:#970000;text-align:left" target="_blank">View LairOut Fullsite</a></small>

Locality

You can pass 'locality' parameter to the map widget url; in this case the server will do an external webservice to a third party service geocoding request, matching the first result of the string passed as locality.
We cannot guarantee that the response if exactly what you were looking for.
Example: http://www.lairout.com/embed/?locality=New%20York

Coordinates

Alternatevely, you can pass the coordinates of the point of interest. The widget uses a default zoom level for this kind of request.
The parameters in this case are: lat / lon
Example: http://www.lairout.com/embed/?lat=40.14318974292438&lon=-75.135498046875

Bounding Box

You can alternatevely pass a bounding box parameter.
Example: http://www.lairout.com/embed/40.14318974292438,-75.135498046875,41.261291493919884,-72.18292236328125

Extra Parameters

You can also specify two extra parameters: starts_on and ends_on.
Those will apply filtering on the event, selecting only the ones that happen in this range of dates selected.
If not specified, the start date will be the current day, and the end date will be +1 month.
If you specify a range that is not at least 1 month, this will be overriden with the default +1 month from the starts_on parameter.

• Developers
• API
• Authentication
• End Points
• Function Reference
• HTTP Response Codes
• Download Events
• • Requested Parameters
  • Response
• Upload/Update Events
• • Requested Parameters
  • Response
• Delete Events
• • Requested Parameters
  • Response
• Map Widget
• Locality
• Coordinates
• Bounding Box
• Extra Parameters