Search Facebook events by location, distance and search terms

As Facebook has discontinued the FQL query API for all apps created after 2014-04-30, it has gotten much more complicated to get public Facebook events by passing a location.

This implementation uses regular Facebook Graph API calls in a three-step approach to get the events:

Search for places in the radius of the passed coordinate and distance (/search?type=place&q={query}&center={coordinate}&distance={distance})
Use the places to query for their events in parallel (/?ids={id1},{id2},{id3},...)
Unify, filter and sort the results from the parallel calls and return them to the client

Known limitations

The Graph API has some "instabilities" with search results. It's possible that the amount of results returned can vary between calls within seconds
The /search endpoint "magically" limits the number of results, independent from the distance used (larger distance doesn't guarantee more results)
Rate limiting will apply, but I experienced no call blocks within a reasonable amount of service requests. Be aware that the way this application works, there are potentially hundreds of (counted) Graph API calls per request to /events.

Installation

As NPM package

The module can be installed via

npm install facebook-events-by-location-core --save

Git

To clone the repository, use

git clone https://github.com/tobilg/facebook-events-by-location-core.git

Usage

The basic usage pattern of this module is the following:

var EventSearch = require("facebook-events-by-location-core");

var es = new EventSearch({
    "lat": 40.710803,
    "lng": -73.964040
});

es.search().then(function (events) {
    console.log(JSON.stringify(events));
}).catch(function (error) {
    console.error(JSON.stringify(error));
});

Access Tokens

The above example expects that the FEBL_ACCESS_TOKEN environment variable is set to a valid App Access Token. Otherwise, you need to specify the accessToken parameter with the request.

Parameters

Mandatory parameters are the following:

lat: The latitude of the position/coordinate the events shall be returned for
lng: The longitude of the position/coordinate the events shall be returned for

Non-mandatory parameters

query: The term(s) on which you want to narrow down your location search (this only filters the places, not the events itself!).
accessToken: The App Access Token to be used for the requests to the Graph API.
distance: The distance in meters (it makes sense to use smaller distances, like max. 2500). Default is 100.
sort: The results can be sorted by time, distance, venue or popularity. If omitted, the events will be returned in the order they were received from the Graph API.
version: The version of the Graph API to use. Default is v2.7.
since: The start of the range to filter results. Format is Unix timestamp or strtotime data value, as accepted by FB Graph API.
until: The end of the range to filter results.

Sample output (shortened)

{
	"events": [{
        "id": "194204067750547",
        "name": "Jessica Hernandez & the Deltas at Baby's All Right",
        "type": "public",
        "coverPicture": "https://scontent.xx.fbcdn.net/v/t31.0-8/s720x720/17758407_10158752838305227_652819766277990370_o.jpg?oh=6f1076521abfe609f45c49f03b6ad3a7&oe=59978EB7",
        "profilePicture": "https://scontent.xx.fbcdn.net/v/t1.0-0/c50.0.200.200/p200x200/17796620_10158752838305227_652819766277990370_n.jpg?oh=b8fd07b35c4f227e4837465e3abe7963&oe=594D43B4",
        "description": "Tuesday June 13 @ Baby's All Right \n\nAdHoc Presents\n\nJessica Hernandez & The Deltas\n\nTIX: http://ticketf.ly/2oawOtz\n\n| Baby's All Right |\n146 Broadway @ Bedford Ave | Williamsburg, Brooklyn \nJMZ-Marcy, L-Bedford, G-Broadway | 7pm | $12+ | 18+\n\nSign up for the mailing list http://tinyurl.com/adhocfmlist\nSubscribe to our events http://facebook.com/adhocfm/events\n\nUpcoming AdHoc Shows\n\n04/13 Entrance (Guy Blakeslee), Ensalmo, Permanent Waves\n04/13 Kane West, Wharfwhit, Bruce Smear, Honnda\n04/14 Pharmakon (Record Release), Coteries, New Castrati\n04/15 Varsity, Fruit & Flowers, Petite League\n04/15 070Shake\n04/16 Lithics, Pucker Up, Bodega, Giggly Boys\n04/20 Helltrap Nightmare: the Hags Return\n04/20 The Coathangers \n04/21 The Coathangers\n04/22 Wolf Eyes (Record Release)\n04/22 Vatican Shadow\n04/23 Tonstartssbandht at The Park Church Co-op\n04/27 HAUX, Dizzy, Aisha Badru\n04/27 Sam Coffey & The Iron Lungs, Mikey Erg, The Othermen The Lame-Os\n04/27 Screaming Females\n04/28 Joakim, Starchild & The New Romantic\n04/28 Laser Background, Operator Music Band, Norwegian Arms, Railings\n04/29 White Lung\n05/02 Novelty Daughter, Elisa, Zenizen, Nicholas Nicholas\n05/03 The Revolution\n05/04 Emo Nite LA w/ special guests\n05/05 Omni, Honduras, Patio\n05/05 Ava Luna, Sammus, Mallrat\n05/05 Crushed (Record Release) w/ Sick Feeling, Neaux, Slashers\n05/05 Ava Luna, Sammus, Mall Rat\n05/05 Beanie Sigel, Manhattan Mal, Young Ros, Tim Wicked\n05/06 HOW SAD, Salt Cathedral\n05/06 Vagabon, Nnamdi Ogbonnaya, So Much Light\n05/07 Mega Bog, Tasseomancy\n05/09 Frank Carter & The Rattlesnakes, Dinosaur Pile-Up, Royal Republic\n05/09 Radkey\n05/09 Chastity at Shea Stadium\n05/09 Frank Carter & The Rattlesnakes, Dinosaur Pile-Up, Royal Republic\n05/10 Savoy Motel, Lionlimb\n05/10 Forest Swords, Actress, Umfang\n05/11 Tall Heights, Henry Jamison\n05/13 Alex Napping (Record Release), Pearer, gobbinjr, Long Neck\n05/13 Midnight Oil - SOLD OUT\n05/14 Midnight Oil\n05/14 Tall Juan (Record Release), Wild Yaks, Ben Katzman's Degreaser\n05/17 Sir Richard Bishop, Robert Millis at The Park Church Co-op\n05/18 Alex G \"Rocket\" Release Show at The Park Church Co-op – Sold Out\n05/18 Rex Orange County\n05/18 Highly Suspect\n05/19 Odwalla1221, Sadaf, Chicklette, Halfpet\n05/20 Adult Mom (Record Release) w/ B.B, Baby Grill\n05/20 Prawn, Mumblr, Wild Pink, Hard Pass\n05/20 Mumdance, Mr. Mitch, Shy Eyez\n05/20 Silent Servant, Not Waving, Pye Corner Audio, Via App\n05/24 Pixies - SOLD OUT\n05/24 Conan, North, False Gods\n05/25 The Walters, Palmas\n05/27 Elf Power, Sunwatchers\n05/27 Lil Debbie\n05/30 Pet Symmetry, Ratboys\n06/03 Chocolat, Bueno\n06/04 The Orbiting Human Circus featuring The Music Tapes\n06/06 Black Marble at Good Room\n06/08 Aldous Harding\n06/08 She-Devils\n06/08 Meatbodies\n06/08 Pelada, CL, Ciarra Black\n06/08 Elysia Crampton, Moor Mother, Total Freedom\n06/09 Girlpool, IAN Sweet, Lexie\n06/09 Mirah\n06/13 Jessica Hernandez & the Deltas\n06/14 Man Forever (Record Release)\n06/15 Sarah Shook & the Disarmers\n06/17 Orchin, Hellrazor, Model/Actriz, Maneka\n06/21 PWR BTTM, Tancred, Fits\n06/24 Julie Byrne at the Park Church Co-op\n07/11 Stolen Jars, Fraternal Twin, Thelma, Poppies\n07/27 Mark McGuire, Ancient Ocean",
        "distance": "89",
        "startTime": "2017-06-13T19:00:00-0400",
        "endTime": "2017-06-13T23:00:00-0400",
        "timeFromNow": 5302362,
        "category": "MUSIC_EVENT",
        "stats": {
            "attending": 3,
            "declined": 0,
            "maybe": 15,
            "noreply": 0
        },
        "venue": {
            "id": "460616340718401",
            "name": "Baby's All Right",
            "about": "babysallright@gmail.com",
            "emails": ["babysallright@gmail.com"],
            "coverPicture": "https://scontent.xx.fbcdn.net/v/t31.0-8/s720x720/16300274_1190598481053513_5678512810993788559_o.jpg?oh=dba6f85205e1c39c2b63ef34595116b3&oe=59587314",
            "profilePicture": "https://scontent.xx.fbcdn.net/v/t1.0-1/p200x200/1480734_642185745894792_5820988503650852577_n.png?oh=c1b2de32d966516538b97e2d3515af69&oe=5984652D",
            "category": "Dance & Night Club",
            "category_list": ["Dance & Night Club", "Breakfast & Brunch Restaurant"],
            "location": {
                "city": "Brooklyn",
                "country": "United States",
                "latitude": 40.71012,
                "longitude": -73.96348,
                "state": "NY",
                "street": "146 Broadway",
                "zip": "11211"
            }
        }
    }],
	"metadata": {
		"venues": 1,
		"venuesWithEvents": 1,
		"events": 4
	}
}

ws/facebook-events-by-location-core