SharkWeek Events API

[mjstallard]

Connect Events API Specification

Introduction

Sssuppppp!!! :sunglasses:

This API endpoint is intended to allow someone to search for events within a given pair of latitude/longitude coordinates and a search radius.

As per the news feed API spec, I'd like to follow JSON API if possible.

Endpoint definition

/events

Query parameters

The parameters that this endpoint requires are:

• latitude, e.g. 42.284901
• longitude, e.g. -71.8255
• radius_miles, e.g. 5

  Response

If no matching events are found, the endpoint should return an empty array of events rather than a 404.

The API will only return results that have an event_date that is today or in the future.

The API will only return results that are within the search radius of the given latitude and longitude coordinate.

The API will return up to 30 results. This matches the current behavior of the iOS app, but we may want to make this either configurable by a query parameter (plus pagination support), or even by an admin setting. This additional control is not required for the first release of the endpoint, however.

Required Fields

The content that is included in a response by default is:

• venue_name, e.g.: "Worcester Bernie HQ"
• venue_city, e.g.: "Worcester"
• venue_state, e.g.: "MA"
• venue_zip, e.g.: "01609"
• venue_address1, e.g.: "256 Park Ave"
• venue_address2, e.g.: "Somewhere"
• venue_address3, e.g.: "Another town"
• venue_latitude, e.g.: 42.284901
• venue_longitude, e.g. -71.8255
• name, e.g. "Worcester Bernie HQ Phone Bank"
• timezone, e.g. "EDT"
• start_time, e.g. "2016-02-08T21:00:00"
• url, e.g. "https://go.berniesanders.com/page/event/detail/volunteeractivityormeetings/4yrp"
• capacity, e.g. 20
• attendee_count, e.g. 1
• event_type_name, e.g. "Phonebank event"
• description, e.g. "The office is open for phonebanking from 4pm to 9pm."
• id, e.g "752b3c2a-a520-49d1-9d43-e101eb9b5e07"

  Sample Response

Something akin to this should work:

   "data":[
      {
         "id":"752b3c2a-a520-49d1-9d43-e101eb9b5e07",
         "type":"event",
         "attributes":{
            "venue_city": "Worcester",
            "venue_name": "Worcester Bernie HQ",
            "venue_zip": "01609",
            "venue_address1": "256 Park Ave",
            "venue_address2": "Cool Road",
            "venue_address3": "Ace Town",
            "venue_state": "MA",
            "venue_latitude": 42.284901,
            "venue_longitude": -71.8255,
            "name": "Worcester Bernie HQ Phone Bank",
            "timezone": "EDT",
             "start_time": "2016-02-08T21:00:00",
             "url": "https://go.berniesanders.com/page/event/detail/volunteeractivityormeetings/4yrp",
             "capacity": 20,
             "attendee_count": 1,
             "event_type_name": "Phonebank event",
             "description": "The office is open for phonebanking from 4pm to 9pm."
         }
      },
      ...
  ]

Sort order

The results should be returned sorted by event date ascending (soonest first), with a secondary sort on distance to the given lat/long pair (i.e. if there's two events with the same start time, then the nearest event is sorted first).

/event/:id

This will return a single record matching the id formatted as per the event above, or a 404.

Sample response

For example, a call to /newsfeed/7de0c82f-2a63-4286-9b5c-84a0917f3a0f would return:

{   
   "data": {
         "id":"752b3c2a-a520-49d1-9d43-e101eb9b5e07",
         "type":"event",
         "attributes":{
            "venue_city": "Worcester",
            "venue_name": "Worcester Bernie HQ",
            "venue_zip": "01609",
            "venue_address1": "256 Park Ave",
            "venue_address2": "Cool Road",
            "venue_address3": "Ace Town",
            "venue_state": "MA",
            "venue_latitude": 42.284901,
            "venue_longitude": -71.8255,
            "name": "Worcester Bernie HQ Phone Bank",
            "timezone": "EDT",
            "start_time": "2016-02-08T21:00:00",
            "url": "https://go.berniesanders.com/page/event/detail/volunteeractivityormeetings/4yrp",
            "capacity": 20,
            "attendee_count": 1,
            "event_type_name": "Phonebank event",
            "description": "The office is open for phonebanking from 4pm to 9pm."
         }
    }
}