Request for location-based API

[kahwee]

Hello!

I wanted to match events and have it be sorted by distance.

The API could be something like:

./api/v1/events/day?lng=103&lat=103
./api/v1/events/hour?lng=103&lat=103
./api/v1/check/2016-07-02?lng=103&lat=103

Suggested cases:

• If lat XOR lng, return error.
• If lat AND lng, use that as point of origin to compute the distance.
• The maximum time window for this API to work is a day, if the user wants to do a month worth of queries, they have collate the results of every day one by one.

The return format should be sorted by distance which is revealed as an additional key in the itemized array of events received.

What do you think?

[sayanee]

Great idea @kahwee!

I like ./api/v1/events/hour?lng=103&lat=103 as it's more intuitive, readable and immediately applicable especially on mobile - we can start with this API endpoint. The interfaces on chat bots / iOS / Android might say: Here are the events happening nearby in the next hour

cc: @cheeaun @subhransu what do you guys think? https://twitter.com/webuildsg/status/743680320549978113

[sayanee]

I'm also wondering if the return json data should contain another node in each event called relative_distance which will have the integer value in km from the user's location. Just sorting might not give enough information.

[subhransu]

yes radius would help.

[cheeaun]

Probably need one more limit, say I might not limit the results by radius, but by the total number of events, all sorted by nearest.

Good reference from Foursquare: https://developer.foursquare.com/docs/venues/search - also have boundary limit (sw and ne) and uses ll for location (comma-separated value)

[sayanee]

cool so it's ./api/v1/events/hour?lng=1&lat=103&limit=5 with radius in each event

[cheeaun]

Huh wait, the radius is for the URL params, distance for the response right (individual events)?

[sayanee]

uh i rather have one word radius and yes we can have that both as part of the API query and the return json

E.g. ./api/v1/events/hour?lng=1&lat=103&limit=5&radius=2 correct @cheeaun?

[sayanee]

Example return query ./api/v1/events/hour?lng=1&lat=103&limit=5&radius=2:

{
  meta: {
    generated_at: "2016-06-20T05:01:15.432Z",
    location: "Singapore",
    api_version: "v1",
    total_events: 3
  },
  events: [
  {
    id: "231387009",
    name: "Singapore MusicTech - June Meetup",
    description: "blah...",
    location: "PayPal 7th Floor, 5 Temasek Blvd, #07-01 Suntec Tower Five, Singapore",
    rsvp_count: 74,
    url: "http://www.meetup.com/Singapore-MusicTech-Meetup/events/231387009/",
    group_id: 19993868,
    group_name: "Singapore MusicTech Meetup",
    group_url: "http://meetup.com/Singapore-MusicTech-Meetup",
    formatted_time: "20 Jun 2016, Mon, 7:00 pm",
    start_time: "2016-06-20T11:00:00.000Z",
    end_time: "2016-06-20T13:00:00.000Z",
    latitude: 1.294414,
    longitude: 103.858093,
    radius: 3
  }
]
}

[notthetup]

Why are we trying to do this on the server side? This can be easily done in a client?

[subhransu]

actually agree with @notthetup. Once we have the latitude and longitude in the initial JSON. We can compute it on the client. Will save us with one more server request.

[cheeaun]

Can also, tho' the accurate way, considering radius of Earth, would be the Haversine formula or use google.maps.geometry.spherical.computeDistanceBetween. Just would be nicer if backend already calculate it and return the distance in meter or something, and let client-side handle unit conversion instead (cough miles cough US cough)

[sayanee]

@notthetup trying to provide an api for 3 clients to do this easily? Yes, agreed about performance and server query time 🤔

[sayanee]

@cheeaun nice! so we can use that tiny function on the client side. Can we only support SI Units? 😝

[kahwee]

I think client side processing of radius made sense. Think about the case of you querying from Tokyo, you get no results if your radius is set to be 50 km but you wouldn't know why. If you return the distance, it's pretty easy to filter down the desired radius.

If the server can handle this, it makes the output of the iOS, Android and, potentially, Facebook Chat bot much more consistent. 😄

[sayanee]

@kahwee Alright, we can create the API endpoints.

We will leave it to the individual client (iOS / Android / chat bots) developers on how they would want to create the relative radius list of events. They can at least check it with the API results 😝

[sayanee]

The question is should we create it here or in the repo https://github.com/webuildorg/webuild-events. I'm fine with webuildsg/webuild temporarily. But eventually will transfer it to webuild-events for modularity.

[notthetup]

I still don't see why the server should do the filtering by lat/long/distance/radius. Especially when all the information needed is available in the API. We are increasing complexity in server for something that can be easily done on the client.

Clients of today are performant enough to be able to do such calculations IMO ( I have no metrics on this, but this is my gut feeling). Also, the size of data we are retrieving is small (if you query the /day end point), and I don't expect it to go to tens of thousands of items size anytime soon, at which point I feel doing it on server side might have performance benefits.

Finally, on consistency, I see why that makes sense, but since all the apps are not made by the same person, or the same group, we are not really going to have similar UX across the apps anyway. So consistency isn't really we are aiming for. I fear not all clients may even use this new API endpoint.

[sayanee]

@kahwee - let's try to implement this on the client side first for the Facebook chat bot https://github.com/webuildsg/bot? See how it works and then we can make a decision

[kahwee]

@notthetup, it goes back to what the We Build SG API is intending to serve. My hope is to make it easier for implementer. If you do not want this to be in the main server at all, I can implement this on the chat server instead of a common server. You are simply suggesting pushing the complexity a layer up to the chat server. There's no right or wrong in this case, either servers requires the same amount of work to be done.

@sayanee Sure.