NAV Navbar
shell python

WebEvents

Introduction

Welcome to the WebEvents API!

WebEvents aims to be the most comprehensive and easy to use events data API on the web. Below are some of the concepts used in the design of the API.

All API keys are limited to 1000 requests a day.

Authentication

# With shell, you can just pass the correct header with each request
curl "https://webevents.org/api/endpoint_here/" \
     -H 'Authorization: Token your_token_here'
# pip install webevents
from webevents import WebEvents

client = WebEvents('your_token_here')

Make sure to replace your_token_here with your API key.

WebEvents expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Token your_token_here

Pagination

Page Size

All endpoints return 100 results per page by default. To change this number for include a limit query param like:

https://webevents.org/api/events/?limit=250

Page size max is 250 results.

Previous and Next Page

All endpoints use offset pagination. Each API response will include pagination information.

To easily paginate through all results, simply request the url in the next key and include your API key in the header. If next is null, you've reached the last page. If prev is null, you're on the first page.

{
  "count": 3658,
  "next": "https://webevents.org/api/events/?limit=250&offset=250",
  "previous": null,
  "results": [
    ...
  ]
}

Events

Get All Events

# pip install webevents
from webevents import WebEvents

client = WebEvents('your_token_here')
client.events()
curl "https://webevents.org/api/events/" \
     -H 'Authorization: Token your_token_here'

The above command returns JSON structured like this:

{
  'count': 3658,
  'next': 'http://webevents.org/api/events/?limit=100&offset=100',
  'previous': None,
  'results': [
    {
      'id': 3,
      'categories': [
        {
          'id': 96,
          'name': 'Literary & Books'
        }
      ],
      'latitude': -86.780871,
      'longitude': 36.164910,
      'title': 'Yelp Study Hall At Industrious Nashville',
      'description': 'Business owners, you\'re never too old for school. But don\'t worry: this isn\'t math or chemistry. We\'re bringing back Study Hall! Remember that? See, not so...',
      'url': 'https://www.yelp.com/events/nashville-yelp-study-hall-at-industrious-nashville',
      'image_url': 'https://s3-media1.fl.yelpcdn.com/ephoto/hWci6psZ3l3y-L5paq-1rQ/o.jpg',
      'place': None,
      'address': '414 Union St Ste 1900',
      'city': 'Nashville',
      'state': 'TN',
      'zip_code': '37219',
      'start': datetime.datetime(2018, 9, 10, 17, 40, 32, 61206),
      'end': datetime.datetime(2018, 9, 10, 17, 40, 32, 61206),
      'minimum_cost': 0.00,
      'maximum_cost': 0.00,
    },
    ...
  ]
}
{
  "count": 3658,
  "next": "http://webevents.org/api/events/?limit=100&offset=100",
  "previous": null,
  "results": [
    {
      "id": 3,
      "categories": [
        {
          "id": 96,
          "name": "Literary & Books"
        }
      ],
      "latitude": "-86.780871",
      "longitude": "36.164910",
      "title": "Yelp Study Hall At Industrious Nashville",
      "description": "Business owners, you're never too old for school. But don't worry: this isn't math or chemistry. We're bringing back Study Hall! Remember that? See, not so...",
      "url": "https://www.yelp.com/events/nashville-yelp-study-hall-at-industrious-nashville",
      "image_url": "https://s3-media1.fl.yelpcdn.com/ephoto/hWci6psZ3l3y-L5paq-1rQ/o.jpg",
      "place": null,
      "address": "414 Union St Ste 1900",
      "city": "Nashville",
      "state": "TN",
      "zip_code": "37219",
      "start": "2018-09-20T20:00:00Z",
      "end": "2018-09-20T22:00:00Z",
      "minimum_cost": "0.00",
      "maximum_cost": "0.00"
    },
    ...
  ]
}

This endpoint retrieves all events.

AND logic is applies to all query parameters.

HTTP Request

GET https://webevents.org/api/events/

Query Parameters

Parameter Required Description
lat false If included, long must also be included.
long false If included, lat must also be included. If no location params are passed, all events will be returned.
radius false Units in miles. If excluded, defaults to 10.
start false UTC datetime string passed in the format of 2013-03-01T01:10:00Z.
end false UTC datetime string passed in the format of 2013-03-01T01:10:00Z.
keyword false Any word or words to search the database for. Multiple words are considered a single literal.
categories false A comma delimited list of category ids from the categories endpoint

Response Fields

Parameter Description
id The ID of the event object
categories An array of category objects related to the event object. Categories can be found in the categories endpoint
latitude The latitude coordinate of the location of the event
longitude The longitude coordinate of the location of the event
title String title of the event
description String description of the event
url URL to event web page where ticket can be purchased or RSVP made
image_url URL to the marketing image for the event
place Name of the event venue
address Address of venue. May also contain secondary address info like suite number
city City of venue
state Two letter abbreviation of venue state
zip_code Zip code of venue
start Start date time of event in UTC
end End date time of event in UTC
minimum_cost Lowest ticket cost tier possible for event
maximum_cost Highest ticket cost tier possible for event. If both minimum_cost and maximum_cost are 0.00, it is safe to assume the event is free.

image_url and place are the only fields that may be null. All other fields will always have values.

Get a Specific Event

# pip install webevents
from webevents import WebEvents

client = WebEvents('your_token_here')
client.events(3)
curl "https://webevents.org/api/events/3/" \
     -H 'Authorization: Token your_token_here'

The above command returns JSON structured like this:

{
  "id": 3,
  "categories": [
    {
      "id": 96,
      "name": "Literary & Books"
    }
  ],
  "latitude": "-86.780871",
  "longitude": "36.164910",
  "title": "Yelp Study Hall At Industrious Nashville",
  "description": "Business owners, you're never too old for school. But don't worry: this isn't math or chemistry. We're bringing back Study Hall! Remember that? See, not so...",
  "url": "https://www.yelp.com/events/nashville-yelp-study-hall-at-industrious-nashville",
  "image_url": "https://s3-media1.fl.yelpcdn.com/ephoto/hWci6psZ3l3y-L5paq-1rQ/o.jpg",
  "place": null,
  "address": "414 Union St Ste 1900",
  "city": "Nashville",
  "state": "TN",
  "zip_code": "37219",
  "start": "2018-09-20T20:00:00Z",
  "end": "2018-09-20T22:00:00Z",
  "minimum_cost": "0.00",
  "maximum_cost": "0.00"
}
{
  'id': 3,
  'categories': [
    {
      'id': 96,
      'name': 'Literary & Books'
    }
  ],
  'latitude': '-86.780871',
  'longitude': '36.164910',
  'title': 'Yelp Study Hall At Industrious Nashville',
  'description': 'Business owners, you\'re never too old for school. But don\'t worry: this isn\'t math or chemistry. We\'re bringing back Study Hall! Remember that? See, not so...',
  'url': 'https://www.yelp.com/events/nashville-yelp-study-hall-at-industrious-nashville',
  'image_url': 'https://s3-media1.fl.yelpcdn.com/ephoto/hWci6psZ3l3y-L5paq-1rQ/o.jpg',
  'place': None,
  'address': '414 Union St Ste 1900',
  'city': 'Nashville',
  'state': 'TN',
  'zip_code': '37219',
  'start': datetime.datetime(2018, 9, 10, 17, 40, 32, 61206),
  'end': datetime.datetime(2018, 9, 10, 17, 40, 32, 61206),
  'minimum_cost': 0.00,
  'maximum_cost': 0.00,
}

This endpoint retrieves a specific event.

HTTP Request

GET https://webevents.org/events/<ID>/

URL Parameters

Parameter Description
ID The ID of the event to retrieve

Categories

Get All Categories

# pip install webevents
from webevents import WebEvents

client = WebEvents('your_token_here')
client.categories()
curl "https://webevents.org/api/categories/" \
     -H 'Authorization: Token your_token_here'

The above command returns JSON structured like this:

{
  "count": 44,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 22,
      "name": "Arts & Culture"
    },
    {
      "id": 25,
      "name": "Auto, Boat & Air"
    },
    {
      "id": 105,
      "name": "Business & Professional"
    },
    {
      "id": 100,
      "name": "Charity & Causes"
    },
    ...
  ]
}
{
  'count': 44,
  'next': None,
  'previous': None,
  'results': [
    {
      'id': 22,
      'name': 'Arts & Culture'
    },
    {
      'id': 25,
      'name': 'Auto, Boat & Air'
    },
    {
      'id': 105,
      'name': 'Business & Professional'
    },
    {
      'id': 100,
      'name': 'Charity & Causes'
    },
    ...
  ]
}

This endpoint retrieves all categories.

HTTP Request

GET https://webevents.org/api/categories/

Get a Specific Category

# pip install webevents
from webevents import WebEvents

client = WebEvents('your_token_here')
client.categories(22)
curl "https://webevents.org/api/categories/22/" \
     -H 'Authorization: Token your_token_here'

The above command returns JSON structured like this:

{
  "id": 22,
  "name": "Arts & Culture"
}
{
  'id': 22,
  'name': 'Arts & Culture',
}

This endpoint retrieves a specific category.

HTTP Request

GET https://webevents.org/categories/<ID>/

URL Parameters

Parameter Description
ID The ID of the category to retrieve



















Icons made by Freepik from www.flaticon.com is licensed by CC 3.0 BY