API Documentation

Before using this API you must obtain a partner ID and an API key from CrowdOptic. To obtain your ID and key please fill out this form.

Per Second Device Report

To use the CrowdOptic sight line cluster detection service you must start with the per second report. It is the method by which devices send sensor data to CrowdOptic as well as the way that CrowdOptic returns clusters detected during that second to the device. The device should attempt to report to this method once per second, if a data report is missed you may resend it but a resend is not necessary.

Data may be sent over http or https and variables may be sent using either the http post or get mechanisms. Data will be returned as a JSON encoded array, all returns can be made human readable appending the variable “format” with the value “dump”.

The first report on app launch should be sent to: https://partner.crowdoptic.com/api/cluster
All subsequent data should be sent to the server address returned as part of the update (more on this below).


Variables to be sent to the server

All variables are required. If your device does not support the variable send a 0.

timestamp The number of seconds, with as much granularity as supported by your device as possible (milliseconds, microseconds, etc.) since the Unix epoch.
token The token is an md5 of the concatenation of the API key you received from CrowdOptic with the timestamp as defined above. Ex: $token=md5(“APIKey”+$timestamp)
partner_id The partner ID you received from CrowdOptic
device_id A unique identifier for each device. Often a md5 of the device's MAC address.
lat The device’s latitude in decimal degrees with as much accuracy as possible.
lng The device’s longitude in decimal degrees with as much accuracy as possible.
alt The device’s altitude in meters above sea level.
hdg The true (not magnetic) heading of the device corrected for device orientation. If possible please use gyroscopic stabilization and a rolling average of samples taken over the course of the second.
acc_x The device’s accelerometer X axis value.
acc_y The device’s accelerometer Y axis value.
acc_z The device’s accelerometer X axis value.
gps_h_acc The device’s horizontal GPS accuracy as defined by the radius of uncertainty measured in meters.
gps_v_acc The device’s vertical accuracy (if supported, if not 0) as defined by the radius of uncertainty measured in meters.
hdg_acc The devices heading accuracy as defined by the the maximum deviation (measured in degrees) between the reported heading and the true heading.
gps_course The direction you are moving as determined by the GPS.
gps_speed The speed that you are moving in meters per second as determined by the GPS.

Variables returned by the server

status 1 = the report was successful (there may have been errors but none were fatal). 0 = a fatal error was encountered.
event_id The event ID you have been geo-located to.
server_address The address of the server where the next per second update should be sent. The first report should always be sent to partner.crowdoptic.com. All subsequent reports should be sent to this address contained in this variable.
sightline_dist The calculated distance of your line of sight.
clusters An array of arrays each sub array contains the following values.
cluster_id The ID of the cluster.
lat The cluster’s latitude
lng The cluster’s longitude.
radius The cluster’s radius.
intersection_count The number of sightline intersections that make up the cluster.
member_count The number of devices in the cluster.
tag_count The number of tags assigned to the cluster.
comment_count The number of comments assigned to the cluster
photo_count The number of photos assigned to the cluster.
video_count The number of videos assigned to the cluster.
last_seen The number of seconds since the cluster has been active

Errors

If there are any issues with the device’s report they will be returned as an array of arrays each containing an ID and a description of the error. Error IDs are as follows.

1 No permission, or token failure
2 Event selection error (device not in event)
3 Variable validation failure or variable not sent
4 device_id not set




User/device authentication

This section provides methods for creating and modifying user accounts as well as linking devices to said accounts. Requests to CrowdOptic should be sent over https and should be sent to the current server address as returned by the per second device report. Return values are in JSON but all returns can be made human readable appending the variable “format” with the value “dump”. All returns will contain a status variable that when set to 1 means the request was processed successfully. If status is set to 0 there was a fatal error and the request was not completed. Variables may be sent via either GET or POST to the address:

https://{server address}/api/user


Authentication Mechanisms

There are two authentication mechanisms contained in this API, device association and session authentication. Device association is less secure but does not require the user to login each time the app is used, rather a device ID is sent with each request and the ID ties the device to the user. To use session authentication the user’s email and password are sent to CrowdOptic via the login method and a session started. A session is also started when a user is added or a device is associated to a user.

Most of the methods described in this document may be called using either authentication type, however there are three methods that must be called with a valid session (updateUsername, updateEmail, and updatePassword), this is done to ensure that a user’s account stays secure even if a device is lost or stolen. If your device does not support storing session cookies or starts a new session for each call, please pass the session_id with each call requiring session authentication. session_id is returned as part of a successful login, device association or user add.

Most API requests require only a device association to function and therefore when presented to the user device association should take the place of logging in. Only if you need to make a call to one of the protected methods described above should they ever need to log in beyond the first device association/account creation.

The flow for authenticating a device

Each time your app loads you should make a call to the checkDeviceAssociated method to see if the device is associated. If it is, then procede to make any other device associated requests.

If it is not associated, you should present your user with the options to: create an account, log into their account, and reset their password. The create account function should send requests to the addUser method, log in to the associateDeviceToUser method, and reset password to the resetPassword method. All methods are described in detail below.

Required variables

As with all CrowdOptic API calls, a method, event_id (returned from the cluster API), timestamp (seconds from the Unix epoch), and a token consisting of an md5 of the concatenation of the API key you received from CrowdOptic and the timestamp as defined above are required.

The required variable names are as follows: (as they are required for each call they will be omitted from the documentation below)

method The method you are calling
event_id The event ID you have been geolocated to, obtained from the per second call.
timestamp The number of seconds since the Unix epoch.
token The token is an md5 of the concatenation of the API key you received from CrowdOptic with the timestamp as defined above. Ex: $token=md5(“APIKey”+$timestamp)

Errors

If there is a fatal error (meaning the request could not be completed) using any of the methods below, CrowdOptic will return a status of 0 and will return an array of errors each with an ID and description. There are both general errors and method specific errors general errors are listed below. Method specific errors will be listed with their respective method.

1 No permission, or token failure
2 Event selection error (event_id not set)
3 Variable validation failure or variable not sent
5 Method not valid
12 Call not made using https

Methods


checkDeviceAssociated

This method checks to see if the device is associated to a user account. It should be called each time the app launches to test if the user needs to be prompted to log in.

Example call:
https://{server_address}/api/user?method=checkDeviceAssociated&event_id=1&timestamp=1373668397437&token=your_token&device_id=your_device_id

Required variables

device_id The device_id to be checked

Returned variables on success

deviceAssociated 1 = The device is associated
0 = The device is not associated

addUser

This method not only adds a user to the database, but also associates the device to the newly created user at the event specified, and logs the user into their new account.

Example call: https://{server_address}/api/user?&method=addUser&event_id=1&timestamp=1373668397437&token=your_token&username=someuser&password=bigsecret&email=email@provider.com&device_id=123abc

Required variables

username The (unique) name that will be displayed on posted media and comments. Only letters and numbers are allowed. 100 Character max length.
password The user's password (please use a double entry compare device side to minimize typos)
email The user's (unique) email address.
device_id The device_id to be associated. More than one device can be associated to a user but not vice versa.

Returned variables on success

session_id the session ID

Method specific errors

6 Email address already in use
7 Username address already in use
8 User already in system and logged in

addUser helper methods

Calls to be asynchronously made in the process of creating an account to notify the user that there are issues with the process before submission. They are optional but will make for a better experience if used.

checkUsername

Checks to ensure that the username is unique and otherwise acceptable to the system.

Example call: https://{server_address}/api/user?&method=checkUsername&event_id=1&timestamp=1373668397437&token=your_token&username=someuser

Required variables

username The username to be checked.

Returned variables on success

result 1 If the username is vacant and meets all criteria.
0 if there are issues with the username.
(if the result is 0) description A description of why the username couldn’t be used (can be returned to user).

checkEmail

Checks to ensure that the email address is unique and otherwise acceptable to the system.

Example call: https://{server_address}/api/user?&method=checkEmail&event_id=1&timestamp=1373668397437&token=your_token&email=someuser@someprovider.com

Required variables

username The username to be checked.

Returned variables on success

result 1 If the username is vacant and meets all criteria.
0 if there are issues with the email.
(if the result is 0) description A description of why the email couldn’t be used (can be returned to user).

associateDeviceToUser

If the user already is in the system but is using a new device or entering a new event, use this method. This method both logs the user in and sets up the permanent association (until disassociateDeviceFromUser is called) between the device and the user.

Example call: https://{server_address}/api/user?method=associateDeviceToUser&event_id=1&timestamp=1373668397437&token=your_token&email=email@provider.com&password=bigsecret&device_id=123abc

Required variables

email The user's email address.
password The user's password
device_id The device_id to be associated. More than one device can be associated to a user but not vice versa.

Returned variables on success

session_id the session ID

Method specific errors

11 Email or password incorrect

disassociateDeviceFromUser

This is similar to logging out but also permanently disassociates the phone from the user.

Example call: https://{server_address}/api/user?method=disassociateDeviceFromUser&event_id=1&timestamp=1373668397437&token=your_token&device_id=1234abc

Required variables

device_id The device_id to be associated. More than one device can be associated to a user but not vice versa.

Returned variables on success

session_id the session ID

resetPassword

If called this will send an email to the address specified with a link to reset their password. It will also disable the current password.

Example call: https://{server_address}/api/user?method=resetPassword&event_id=1&timestamp=1373668397437&token=your_token&email@provider.com

Required variables

email The user’s email address.

Returned variables on success

session_id the session ID

Method specific errors

9 New email address is already in use

Methods using session authentication


checkSessionAuthenticated

This method checks to see if there is an active session that will enable a user to edit their personal details.

Example call: https://{server_address}/api/user?method=checkSessionAuthenticated&event_id=1&timestamp=1373668397437&token=your_token

Returned variables on success

sessionAuthenticated 1 = The device is authenticated
0 = The device isn’t
(if sessionAuthenticated = 1) session_id The session ID

login

This method logs in a user and sets up their session. It is required that a session be active and a user logged in if said user wants to update their account details. You can check if a user is logged in by using the checkSessionAuthenticated method.

Example call: https://{server_address}/api/user?method=login&event_id=1&timestamp=1373668397437&token=your_token&email=email@provider.com&password=bigsecret

Required variables

email The user's (unique) email address.
password The user's password (please use a double entry compare device side to minimize typos)

Returned variables on success

session_id the session ID

Method specific errors

11 Email or password incorrect

logout

This method logs out a user and destroys their session.

Example call: https://{server_address}/api/user?method=logout&event_id=1&timestamp=1373668397437&token=your_token

updateUsername

This method changes a user’s username to the username sent. The user must be logged in with an active session to use this method.

Example call: https://{server_address}/api/user?method=updateUsername&event_id=1&timestamp=1373668397437&token=your_token&username=the_new_username

Required variables

username The new username, to update to

Method specific errors

7 New username already in use

updateEmail

This method changes a user’s email address to the email address sent. Please use a double entry confirmation device side to prevent a user from locking themselves out if they mistype their address. The user must be logged in with an active session to use this method.

Example call: https://{server_address}/api/user?method=updateEmail&event_id=1&timestamp=1373668397437&token=your_token&email=new@email.com

Required variables

email The new email, to update to

Method specific errors

6 New email address already in use

updatePassword

This method changes a user’s password to the password sent. Please use a double entry confirmation device side to prevent a user from locking themselves out if they mistype their password. The user must be logged in with an active session to use this method.

Example call: https://{server_address}/api/user?method=updateEmail&event_id=1&timestamp=1373668397437&token=your_token&email=new@email.com

Required variables

password The new password, to update to

Returned variables on success

session_id the session ID