Location Sharing

Base URL for requests

https://verizonventures-prod.apigee.net/glympse

Introduction

The Glympse REST API uses simple GET or POST requests that return JSON responses. Unless noted, parameters for requests are passed as standard HTTP name/value pairs on the QueryString. Authentication is based on OAuth2 which means that all requests MUST be made over a SSL connection using HTTPS.

Technically speaking, you only need the API Key for account creation and account login. At which point you will be issued a temporary OAuth2 token. The OAuth2 token, which is a required parameter for the remaining APIs, is implicitly tied to your API Key.

Rate Limiting

Usage of the API is subject to rate limits that are tied to your API Key. The limits are based on a moving window that tracks the number of requests sent per hour. The current limits should be completely sufficient for your needs, but if you find them inadequate, please contact us.

Standard Response Structure

All responses have the same style and formatted JSON structure. The goal is to support a variety of result codes, but also allow for more detailed descriptions in somewhat human readable form. Every response has a result string indicating the "success" or "failure" of the API call. The portion of the result which is call specific will be specified within the response object of the result. On failure, the response object will contain an empty object.

Every response object has a "type" name/value pair which indicates the type of object in the response. Additionally, meta data about the response may be provided to aid application developers during code development. The meta data, provide in the "meta" object of the result, may include the server time, the IP address of the server fulfilling the request, and any extended error information about a failed request.

Some Terminology and Background

If you are new to Glympse, here are some quick bullet points to help you understand some of the terminology used in this document.

  • To avoid confusion with Glympse "the company" and “Glympse " the thing you create and send to people", we use the word "Ticket" in the API to mean "the thing you create and send to people". So when using the Glympse API, you create Tickets and send Invites to other people to view the Tickets.
  • A User object is a lightweight object that represents a user in our system. The User object has attributes such as a nickname and an avatar and, more importantly, credentials which are used to authenticate the Glympse user to our servers. This authentication is currently performed via a randomly generated Glympse username and password that the end user never sees (remember, from the end user's perpsective, the Glympse app requries no registration), however, in the future, the user could be verified by binding to a third party account like Facebook or Twitter.
  • A Ticket object is the primary object of the Glympse system. It is the object that a person or device creates when they wish to share their location. It contains a start_time and an end_time which time bounds the duration for which the person or device shares their location.
  • A Ticket object contains 2 streams, each of which is effectively a time-stamped sequence of records: a location stream and a data stream (consisting of name/value pairs). The core information that a user chooses to share with others is captured in these streams. The collection and dissemination of this information is controlled and bounded by the start_time and end_time of the ticket. The location stream contains time-stamped location points and is optimized for location data. It contains native fields for latitude, longitude, speed, heading, altitude, horizontal accuracy, and vertical accuracy. The data stream contains time-stamped name value pairs such as messages, destination, nicknames, avatar URLs, etc. The data stream also supports a company ID field so that third party apps can store custom per-app data--say, golf scores or heart rates at a particular time/location.
  • An Invite object is used to share a Ticket with others. In today's world, when you "Send a Glympse" to someone, that someone receives a URL with a random 6 letter code at the end (like ABC-123). Internally, that 6 letter code is backed by an Invite object in the Glympse system. For any given Ticket, the user may create 0 or more Invite objects, depending on how many people they wish to share that ticket with. An Invite doesn't necessarily map to a single viewer – you can create an Invite and send it to Facebook or Twitter, in which case many users may view the Ticket through that single Invite code. To put it in other words, an Invite is sort of a unique alias for a Ticket that allows certain users to view the Ticket. The advantage to creating multiple Invites for a single Ticket is that you can track each Invite for information such as number of views, last viewed time, etc.
  • An Invite object contains 0 or more Viewer objects. A Viewer object attempts to uniquely identify each viewer for a particular Invite. For example, if a user were to create an Invite for a Ticket and post that Invite URL on Facebook, then all of that user's Facebook friends could click on that link and view the user's Ticket. Through a system of browser cookies and API parameters, the Glympse system is able to identify the set of unique users viewing that Invite URL. In the end, the user who posted the Glympse to Facebook would like to know how many people viewed it. And through which invite. Each Viewer object represents a single unique viewer for a given Invite. The Invite object can roll this list up into a "number of viewers" count.

Data Types

From an API standpoint, here are some important data types that are used to store the ids representing the above objects and other concepts.

Name Data type Description
user_id Int64 Uniquely identifies a user in the entire Glympse system.
ticket_id Int64 Uniquely identifies a ticket in the entire Glympse system.
There are multiple tickets per user.
stream_id Int64 Uniquely identifies a ticket in the entire Glympse system.
There are multiple streams per ticket.
invite_code String This is the 6+ letter code that allows an invitee to view a ticket.
There is one invite code per invitee.
viewer_id UUID Uniquely identifies a viewer in the entire Glympse system.
There are multiple viewers per invite.
timestamp Int64 All timestamps (start_time, end_time, etc.) are in Unix milliseconds.

 

Rest API

 

 

account

API Description
POST account/confirm Confirms a contact confirmation code exposed in a email or some other unauthenticated delivery method.
POST account/create Creates a new user account and login and exposes parameters for account sharing.
POST account/login Generates an access_token for all other API endpoints.

batch

API Description
POST batch Allows the caller to batch multiple endpoint requests into a single HTTP request, upon which the server will issue the requests on the client's behalf.

config

API Description
GET config Returns the latest server configuration settings for the associated API Key

contacts

API Description
GET users/{id}/contacts Retrieves all contact information
POST users/{id}/contacts/confirm Allows an authenticated client to confirm a contact via a confirmation code
POST users/{id}/contacts/{contact_id}/delete Deletes the specified contact
POST users/{id}/contacts/register Allows a client to register new contact information of various types includinge email, sms, or address. For sms and email addresses, this generates a confirmation code which is sent to the specified contact address allowing for confirmation of the address within a given period of time

groups

API Description
GET groups Enumerates all of the group ids of which the user is a member
GET groups/{id} Retrieves information about a given group. If the group is not public, the user must be authenticated and a member of the group.
POST groups/{id}/create_invite Creates an invite to join a group
GET groups/{id}/events Enumerates the latest events that have occurred within a group
POST groups/{id}/join Enables the current user to join a group
POST groups/{id}/leave Removes the current user from a group
POST groups/{id}/set_password Changes the password protecting group joins.
POST groups/{id}/update Updates the name of a private group
POST groups/{id}/upload_avatar Uploads an image to be used as an avatar the private group
GET users/{id}/groups Enumerates all of the group ids of which the user is a member

invites

API Description
GET invites Enumerates all the invites sent by the user which have changed or been viewed since the last_refresh time.
GET invites/{id} Returns the data associated with the invite code. This may be a ticket_invite, ticket_request, or group_invite
POST invites/{id}/create_trigger Allows a client to create a trigger on the invite
POST invites/{id}/delete Deletes the specified invite and prevents it from being viewed
POST invites/{id}/delete_trigger Allows a client to delete a trigger from an invite
GET invites/{id}/properties Returns only the properties associated with the invite code. This may be a ticket_invite, ticket_request, or group_invite
POST invites/{id}/route Calls the maps service to return a route for a given invite code
POST invites/{id}/snapshot Returns the URL of the snapshot of the ticket identified by invite id.
GET invites/{id}/triggers Allows a client to list all triggers on the invite
POST invites/{id}/update Allows a client to update the send status of a client sent invite
GET users/{id}/invites Enumerates all the invites sent by the user which have changed or been viewed since the last_refresh time.

linked_accounts

API Description
GET users/{id}/linked_accounts Enumerates all the third party accounts (e.g., Facebook, Twitter, Evernote etc.) linked to this Glympse user
POST users/{id}/linked_accounts/{type}/link Link a third party identity to a Glympse account. Uses the third party identity to facilitate a unified Glymspe experience across multiple devices.
POST users/{id}/linked_accounts/{type}/refresh Refreshes the third party token for a third party account (Facebook, Twitter or Google+) that's linked to a Glympse account.
POST users/{id}/linked_accounts/{type}/unlink Unlink a third party auth service like Facebook or Twitter from a Glympse account.

pairing

API Description
GET account/pairing Generates a pairing code on the linked device
GET account/pairing/{code} Gets the status of a pairing code.
POST account/pairing/{code}/confirm Confirms that the given pairing code should be linked with this account.

ping

API Description
GET ping Returns the REST API server status and current assembly versions

tickets

API Description
GET tickets Enumerates all of the tickets created by the user in the last 30 days (or less).
POST tickets/append_data Appends time-stamped name/value pairs to all active tickets owned by the user and device, or only the tickets specified by the ids parameter.
POST tickets/append_location Appends location values to all active tickets owned by the user and device, or only the tickets specified by the ids parameter.
GET tickets/{id} Allows the owner of a given ticket to receive envelope information about the ticket without any stream data.
POST tickets/{id}/append_data Appends time-stamped name/value pairs to all active tickets owned by the user and device, or only the tickets specified by the ids parameter.
POST tickets/{id}/append_location Appends location values to all active tickets owned by the user and device, or only the tickets specified by the ids parameter.
POST tickets/{id}/create_invite Creates and optionally sends an invite to view a ticket
POST tickets/{id}/delete Deletes the ticket so that no future updates or invites can modify or view the ticket.
POST tickets/{id}/expire Expires an active ticket.
POST tickets/{id}/set_ownership Allows a device to set ownership of a ticket to a server owned device and enabled location data to be appended to the streams by this server owned device In the first version, it will only allow one ticket to be set
POST tickets/{id}/set_visibility Allows the visibility of a location stream to be controlled for a single ticket. If location visibility is set to hidden, future calls to append_location which not append location data to this ticket.
POST tickets/{id}/take_ownership Allows a device to take ownership of a sibling ticket and enabled data to be appended to the streams by this device
POST tickets/{id}/update Modifies the duration an existing ticket.
GET users/{id}/tickets Enumerates all of the tickets created by the user in the last 30 days (or less).

users

API Description
GET users/{id} Retrieves the nickname and avatar for the specified user
POST users/{id}/create_group Creates and joins a new group.
POST users/{id}/create_request Creates a request for another user to respond with an invite.
POST users/{id}/create_ticket Creates a new ticket for location sharing.
POST users/{id}/echo echo end point for the authenticated user to send push back to server so server can validate token
GET users/{id}/received_invites Returns the list of recently received invites. Currently this is only viewed invites.
POST users/{id}/register_device Registers a device for the authenticated user to receive push notifications.
POST users/{id}/unregister_device Unregisters the sending device from push notifications.
POST users/{id}/update Updates the user's nickname
POST users/{id}/upload_avatar Uploads an image to be used as an avatar for the current user

Additional information about the Glympse platform functionality is available here.