Arlo

REST Pub API: Venues

The Venues collection resource can be used to retrieve the public details of venues, including their name, physical address and geo (map) points, plus facility information such as directions and parking. This resource is read-only.

This resource can return a collection of all available venues (useful for producing navigation lists), or the details of a specific venue instance (useful for retrieving data when generating a specific venue page). The specification of both is covered in this article.

Venue instance resource

Provides access to individual venue instances by ID. Skip to an an example request.

Resource URI

/api/2012-02-01/pub/resources/venues/{id}

General structure

{
   "VenueID":9003,
   "Name":"Mercure Hotel Windsor",
   "FacilityInfo":{
      "Directions":{
         "ContentType":"application/xhtml",
         "Text":"<p>Opposite McDonalds and BNZ. Next to the large Stirling Sports shop. The entrance is on Willis street.</p>"
      },
      "Parking":{
         "ContentType":"application/xhtml",
         "Text":"<p>Wilson pubic parking is available at 123 Willis sty (North end). Street parking is also available, but it can be difficult to get a park and the maximum time you can stay is 2 hours.</p>"
      }
   },
   "GeoData":{
      "PointLatitude":-34.932065,
      "PointLongitude":138.604618
   },
   "PhysicalAddress":{
      "StreetLine1":"58-60 Queen Street",
      "City":"Adelaide",
      "State":"SA",
      "PostCode":"5000",
      "Country":"Australia"
   }
}

Item fields

Field Description
VenueID An integer value that uniquely identifies this resource within the platform.
Name A string representing the name of the name of the venue, up to 256 characters long.
LocationName String display value describing the locality. By default this value is often the city of the venue, but may be customised to be any string such as state or suburb.
GeoData A structure containing geographical coordinates of the venue location, used with mapping APIs. This field is present only if map data for the venue is available.
Structure fields
  • PointLatitude: A float value with the latitude coordinate value.
  • PointLongitude: A float value with the longitude coordinate value.
PhysicalAddress A structure representing the physical address of the venue. This field is present only if address information for the venue is available.
Structure fields
  • StreetLine1: Line 1 of the street address.
  • StreetLine2: Line 2 of the street Address.
  • StreetLine3: Line 3 of the street Address.
  • StreetLine4: Line 4 of the street Address.
  • Suburb: The address suburb.
  • City: The address city.
  • State: The address state.
  • PostCode: The address post code.
  • Country: The address country.
FacilityInfo A FacilityInfo structure containing parking and directions information for the venue. This field is only present if this facility information is available.
ViewUri String representing a URI containing more information about the venue. This field is present only if a URL with additional information is available.

FacilityInfo fields

Field Description
Directions A structure containing marked-up text representing directions to reach the venue. This field is only present if directions content is available. This field is often not suitable for display in lists and can contain arbitrary HTML including tables, lists and images.
Structure fields
  • ContentType: String representing the content type of the information, usually application/xhtml.
  • Text: Text content of the information.
Parking A structure containing marked-up text representing parking details for the venue. This field is only present if parking content is available. This field is often not suitable for display in lists and can contain arbitrary HTML including tables, lists and images.
Structure fields
  • ContentType: String representing the content type of the information, usually application/xhtml.
  • Text: Text content of the information.

HTTP GET

Returns a representation of a venue by ID, including the properties above.

Optional parameters
Parameter Description
format String representing the required response format. Only required if an Accept HTTP header is not provided. Supported values: json

NOTE: If this parameter is missing and no valid Accept header is supplied, the API will return a 406 Not Acceptable response.
callback The script function to call with response data if this call is to be executed as a jsonp request. The HTTP content type for the response will be application/javascript.
fields A list of comma-separated values representing the required fields in the response payload. Supported values (field names) are listed in the item fields section. Field names are not case sensitive. Default is VenueID,Name,ViewUri
Response

See HTTP response codes and error handling for more information on the possible responses and codes returned by this resource.

Example

Retrieve the details for a venue with ID 1622, including their full name, profile, social network information and URL to a page with more information.

GET /api/2012-02-01/pub/resources/venues/1622/?format=json&fields=Name,GeoData,ViewUri

{
   "Name":"Pacific Park Hotel",
   "GeoData":{
      "PointLatitude":-36.8442884,
      "PointLongitude":174.7335927
   },
   "ViewUri":"http://acme.example.org/venues/9036-pacific-park-hotel"
}

HTTP POST

Not supported.

HTTP PUT

Not supported.

HTTP DELETE

Not supported.

Venues collection resource

Retrieves a list of venue instances for all available venues in the platform. Skip to an example request.

Resource URI

/api/2012-02-01/pub/resources/venues/

General structure

This resource returns a collection entity with a StartIndex, Count and Items collection containing venue instances.

{
   "StartIndex":0,
   "Count":20,
   "Items":[
      {
         "Name":"Mercure Hotel Windsor",
         "GeoData":{
            "PointLatitude":-34.932065,
            "PointLongitude":138.604618
         },
         "PhysicalAddress":{
            "StreetLine1":"58-60 Queen Street",
            "City":"Adelaide",
            "State":"SA",
            "PostCode":"5000",
            "Country":"Australia"
         },
         "ViewUri":"http://acme.example.org/venues/9003-mercure-hotel-windsor"
      },
      {
         "Name":"Gryphon Theatre",
         "GeoData":{
            "PointLatitude":-41.2935534,
            "PointLongitude":174.7769996
         },
         "PhysicalAddress":{
            "StreetLine1":"Gryphon Theatre",
            "StreetLine2":"22 Ghuznee Street",
            "City":"Wellington",
            "Country":"New Zealand"
         },
         "ViewUri":"http://acme.example.org/venues/9011-gryphon-theatre"
      },
      {
         "Name":"Kingsgate Hotel",
         "GeoData":{
            "PointLatitude":-45.8727968,
            "PointLongitude":170.5007866
         },
         "PhysicalAddress":{
            "StreetLine1":"Kingsgate Hotel",
            "StreetLine2":"10 Smith Street",
            "City":"Dunedin",
            "Country":"New Zealand"
         },
         "ViewUri":"http://acme.example.org/venues/9013-kingsgate-hotel"
      },
      {
         "Name":"Pacific Park Hotel",
         "GeoData":{
            "PointLatitude":-45.8662441,
            "PointLongitude":170.4992206
         },
         "PhysicalAddress":{
            "StreetLine1":"Pacific Park Hotel",
            "StreetLine2":"22-24 Wallace Street",
            "City":"Dunedin",
            "Country":"New Zealand"
         },
         "ViewUri":"http://acme.example.org/venues/9014-pacific-park-hotel"
      },
      ...   
   ]
}

Collection fields

Field Description
StartIndex The start index of the first item in the payload within the overall result set. Used for paging.
Count The number of items returned in the payload in the Items array. This value is different to the total number of results in the overall result set (the TotalCount field). Used in paging and represents the page size.
TotalCount The total number of results in the overall result set. This field is not included unless explicitly requested in the optional parameters.
Items An array of venue instance records.

HTTP GET

Returns a collection of all venues, including the properties above.

Optional parameters
Parameter Description
format String representing the required response format. Only required if an Accept HTTP header is not provided. Supported values: json

NOTE: If this parameter is missing and no valid Accept header is supplied, the API will return a 406 Not Acceptable response.
callback The script function to call with response data if this call is to be executed as a jsonp request. The HTTP content type for the response will be application/javascript.
fields A list of comma-separated values representing the required fields for each record in the response payload. Supported values (field names) are listed in the item fields section. Field names are not case sensitive. Default is VenueID,Name,ViewUri
skip The number of records to skip in the source results before returning the response payload. Used for paging. Default is 0.
top The maximum number of records to return in the response payload. Used for paging. Default is 20. The maximum supported value is 200.
includeTotalCount Boolean value determining whether an additional property (TotalCount) is included in the response respresenting the total count of matching records on the server, independent of the count of records actually returned in the response payload. Used for paging. Supported values: true, false. Default is false.
region String representing the region to use when retrieving venue information.

Used only in platforms that have multiple regions installed. This value influences which venues are returned — only venues promoted in the specified region will be included.

Supported values are dependent on regions installed on the platform. If not specified, the default region for the platform will be used when evaluating the request.
Response

See HTTP response codes and error handling for more information on the possible responses and codes returned by this resource.

Example

Retrieve a collection with details of all venues, including their name and URI link.

GET /api/2012-02-01/pub/resources/venues/?format=json&fields=Name,ViewUri

HTTP POST

Not supported.

HTTP PUT

Not supported.

HTTP DELETE

Not supported.