Location Relay API

Hand-crafted API doc for the location relay service.
/follow/user
Post a location to the service.
Method
POST
Request
    {
        groupId: "your group id",
        userId: "your user id",
        location: {
            lat: latitude,
            lng: longitude,
            time: timestamp for this location (ms since 1/1/1970 00:00:00),
            accuracy: accuracy circle in meters,
            speed: optional in meters/second,
            heading: optional in degrees
        },
        options: {
            follow_type: one of "orbit", "free_look", "leash",
            cruise: one of "forward", "pause", "reverse",
            look_at_me: true or false
        }
    }
Response
    {
        status: "Message if all is well"
        error: "Message if something went wrong",
        it: true/false
    }
Notes
Post location updates with this API to have them appear to subscribers to the group identified by groupId.

When a client follows the user identified by userId, the it field in the response is true; otherwise it's not. The target can thus tell if they're being tracked specifically, vs just appearing as one of multiple users moving about in a group.

When a target is being tracked specifically, the options in the POST body have the potential to affect the manner in which they're followed (assuming the client receiving the notifications agrees). The follow_type attribute specifies which follow mode to use (if applicable). The cruise value specifies whether the copter should try to orbit the target (which actually only applies if follow_type is "free_look" or "orbit").

If all goes well, you'll get a status field in the response; its presence in the response body indicates that things went well. If things go badly, there will instead be an error field in the response. And, it will say something about what went wrong.

NOTE: When you are done being followed, send a DELETE to /follow/user/:groupId/:userId. This will immediately tell any subscribed clients that you're not around, and they can stop tracking you.
/follow/user/:groupId/:userId
Exit follow mode (delete a user from a group)
Method
DELETE
Request
Nothing to speak of.
Response
    {
        status: "Message if all is well"
        error: "Message if something went wrong"
    }
Notes
Call this when you're ready to stop being followed. The user is removed from the group, and all subscribers to the group are notified that you've exited.
/follow/group/:groupId
Delete an entire group
Method
DELETE
Request
Nothing to speak of.
Response
    {
        status: "Message if all is well"
        error: "Message if something went wrong"
    }
Notes
Call this to delete an entire group. One thing to note: If you delete a group and there are still users in it posting locations, it will re-appear. So this is really only valid if you know the users have all stopped reporting locations. Or if you want to remove stale users from an active group, you could probably use it for that.
/follow/user/:groupId/:userId
Exit follow mode (delete a user from a group)
Method
DELETE
Request
Nothing to speak of.
Response
    {
        status: "Message if all is well"
        error: "Message if something went wrong"
    }
Notes
Call this when you're ready to stop being followed. The user is removed from the group, and all subscribers to the group are notified that you've exited.
/follow/group/:groupId
Delete an entire group
Method
DELETE
Request
Nothing to speak of.
Response
    {
        status: "Message if all is well"
        error: "Message if something went wrong"
    }
Notes
Call this to delete an entire group. One thing to note: If you delete a group and there are still users in it posting locations, it will re-appear. So this is really only valid if you know the users have all stopped reporting locations. Or if you want to remove stale users from an active group, you could probably use it for that.
======= >>>>>>> apidoc/more
/follow/groups
List all groups
Method
GET
Request
Nothing to speak of.
Response
    [
        test_group: {
            test_user: {
                loc: {lat: 123, lng: 234, altitude: 800, accuracy: 10, speed: 5, time: 1289320229}
            }
        },
        some_other_group: {
            some_user: {
                loc: {lat: 123, lng: 234, altitude: 800, accuracy: 10, speed: 5, time: 1289320229}
            }
        }
    ]
Notes
Call this to see a listing of all groups and all users within groups.
/follow/group/:groupId
Get users within a specified group
Method
GET
Request
Nothing to speak of.
Response
        test_group: {
            test_user: {
                loc: {lat: 123, lng: 234, altitude: 800, accuracy: 10, speed: 5, time: 1289320229}
            }
        }
Notes
Call this to see a listing of all groups and all users within groups.
/follow/user/:groupId/:userId
Get a specific user's location within a group
Method
GET
Request
Nothing to speak of.
Response
        loc: {lat: 123, lng: 234, altitude: 800, accuracy: 10, speed: 5, time: 1289320229}
Notes
TIP: Don't use this. Subscribe to a specific user instead.