GET ​/api​/v3​/venues

Return a list of venues near a location.

Request

Example Request

{
  "lat": {
  },
  "lng": {
  },
  "radius": {
  },
  "genres": "Jazz,Blues",
  "genres_excluded": "Metal,Country",
  "from_date": 20150820,
  "to_date": 20150820,
  "page": 1,
  "per_page": 30,
  "minimum_upcoming_gigs": 76
}

Example Parameters

  • lat: Latitude

    • Required: yes
    • Type: Float
    • Example: 34.7971938
  • lng: Longitude

    • Required: yes
    • Type: Float
    • Example: -122.4053625
  • radius: Radius in miles from the lat/lng center point.

    • Required: yes
    • Type: Float
    • Example: 20
  • genres: A comma separated list of genres to include in the search. Will return a count of the artists playing at this venue matching the selected genre criteria.

    • Required: no
    • Type: string
    • Example: Jazz,Blues
  • genres_excluded: A comma separated list of genres to exclude in the search. Will return a count of the artists playing at this venue matching the selected genres excluded criteria.

    • Required: no
    • Type: string
    • Example: Metal,Country
  • from_date: Date in format YYYYmmdd, to begin date range from

    • Required: no
    • Type: string
    • Example: 20150820
  • to_date: Date in format YYYYmmdd, to end date range at

    • Required: no
    • Type: string
    • Example: 20150820
  • page:

    • Required: no
    • Type: integer
    • Example: 1
    • %{key} %{@schema[key]}
  • per_page: Number of records to return in each page. Default is 20. Larger page sizes decrease performance, so choose the smallest size that works for your client.

    • Required: no
    • Type: integer
    • Example: 30
  • minimumupcominggigs: Minimum number of upcoming gigs a venue must have to be included. Default is three or more.

    • Required: no
    • Type: integer

Response

Example Response

{
  "meta": {
    "page": 1,
    "per_page": 20,
    "total_pages": 61,
    "records": 1204
  },
  "venues_meta": {
    "followers_url": "https://deliradio.com/api/v3/venues/followers?ids=356225,342198,356226,324289,258603,288070&key=7bacd6f60138nan2dace4d56c13a5d4f6\""
  },
  "venues": [
    {
      "id": 1,
      "name": "The Palladium",
      "latitude": {
      },
      "longitude": {
      },
      "address": "1221 Main St",
      "capacity": 100,
      "city": "Los Angeles",
      "description": "Featuring Magnifi",
      "province": "CA",
      "country": "USA",
      "station_title": "The Palladium Radio",
      "venue_banner_url": "http://example.com/foo/bar/venue.jpg",
      "website_url": "http://example.com/foo.html",
      "slug": "palladium-radio",
      "you_follow": true,
      "facebook_page_url": "http://facebook.com/the-palladium",
      "total_artist_count": 15,
      "genre_artist_count": 4,
      "twitter_username": "Palladium",
      "official_station_id": 123,
      "has_music": true
    }
  ]
}

Response Parameters

  • meta:

    • Required: no
    • page: The current page number
      • Required: no
      • Type: integer
      • Example: 1
    • per_page: The number of records returned in each page.
      • Required: no
      • Type: integer
      • Example: 20
    • total_pages: The total number of pages available to request.
      • Required: no
      • Type: integer
      • Example: 61
    • records: The total number of records available across all pages.
      • Required: no
      • Type: integer
      • Example: 1204
  • venues_meta:

    • Required: no
    • followers_url: a preconstructed URL you can use to gather follower information for the venues returned in this response.
      • Required: no
      • Type:
        • null
        • string
      • Example: https://deliradio.com/api/v3/venues/followers?ids=356225,342198,356226,324289,258603,288070&key=7bacd6f60138nan2dace4d56c13a5d4f6"
  • venues:

    • Required: no
    • Type: array
    • Items

      • Required: no
      • id: Venue ID
        • Required: no
        • Type: integer
        • Example: 1
      • name: The name of the venue
        • Required: no
        • Type: string
        • Example: The Palladium
      • latitude: The latitude of the venue
        • Required: no
        • Type: Float
        • Example: 34.7971938
      • longitude: The longitude of the venue
        • Required: no
        • Type: Float
        • Example: -122.4053625
      • address: The street address of the venue
        • Required: no
        • Type:
          • null
          • string
        • Example: 1221 Main St
      • capacity: Capacity of venue
        • Required: yes
        • Type: integer
        • Example: 100
      • city: The venue's city
        • Required: no
        • Type: string
        • Example: Los Angeles
      • description: description of venue
        • Required: no
        • Type:
          • null
          • string
        • Example: Featuring Magnifi
      • province: The venue's state or province
        • Required: no
        • Type: string
        • Example: CA
      • country: The venue's country
        • Required: no
        • Type: string
        • Example: USA
      • station_title: The name of the venue's station
        • Required: no
        • Type:
          • null
          • string
        • Example: The Palladium Radio
      • venuebannerurl: A url to an image that can be displayed for the venue
        • Required: no
        • Type:
          • null
          • string
        • Example: http://example.com/foo/bar/venue.jpg
      • website_url: A url to a venue website
        • Required: no
        • Type:
          • null
          • string
        • Example: http://example.com/foo.html
      • slug: The unique slug for a venue.
        • Required: no
        • Type:
          • null
          • string
        • Example: palladium-radio
      • you_follow: Indicates if the current account has favorited/followed this venue.
        • Required: no
        • Type: boolean
        • Example: true
      • facebookpageurl: The facebook page of the venue, if they have one.
        • Required: no
        • Type:
          • null
          • string
        • Example: http://facebook.com/the-palladium
      • totalartistcount: The total number of upcoming artists playing at this venue.
        • Required: no
        • Type: integer
        • Example: 15
      • genreartistcount: The total number of upcoming artists playing at this venue that match the provided genre criteria in the request.
        • Required: no
        • Type: integer
        • Example: 4
      • twitter_username: The twitter account of the venue, if they have one. Does not include a preceding @ symbol.
        • Required: no
        • Type:
          • null
          • string
        • Example: Palladium
      • officialstationid: The ID for the official station for this venue
        • Required: yes
        • Type:
          • null
          • integer
        • Example: 123
      • has_music: Indicates if venue has any music
        • Required: yes
        • Type: boolean
        • Example: true

Response Codes

Successful Response Codes

  • 200:

Failure Response Codes

  • 400: One or more parameters were missing or invalid.