Diveboard API 0.5.md

PUBLIC API SPECIFICATION

Date	Version	Comment
	0.1	First version of the specification
April 25th 2012	0.2	Updated the vanity_url, login_email and login_fb apis Updated behavior of how species array is being stored in dives (s- replaces c-)
May 4th 2012	0.3	Deprecate use of location_id and region_id in setters, replaced by location object and region object you must update your code from object_id => id to object => {"id" => id}
October, 26th 2012	0.4	Adding the new calls and parameters apikey gets mandatory
December, 20th 2012	0.5	Support for comma separated flavours
February, 5th 2014	0.6	Updated version, deprecating attributes without _value/_unit
October 2nd 2014	0.7	added wallet pictures

Table of content

[[TOC]]

Terms of Use of the API

(a) To make it possible for Materials of the Site to be accessible to new technologies, we have developed a series of Application Programming Interfaces ("APIs") that allow for the Materials to be retrieved by technologies using certain computer programming methodologies. The APIs are freely available for anyone to use. You must register with the Site by emailing ‘[email protected]’ to indicate your desire to use them, which will allow us to better support your use of the API. Upon registration, a unique API key code will be issued to you which you will need to be including in upcoming requests as described in the API Documentation.

(b) If you develop a technology as a result of your use of the Site and the Materials on the Site, we encourage you to provide us with information about such technology. Sharing your success with us will help foster the Diveboard community by providing examples of success. We may choose to feature your story on the Site, or highlight your technology or product on the Site.

(c) The Data published through Diveboard is licenced under Creative Common’s is licensed under a Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License . Published data coming from Diveboard must link back to their location on Diveboard. Modification or corrections are only allowed through the APIs. If you are the original creator of a content you are free to push/pull/modify/delete such content. Diveboard may keep anonymized scientific data upon delete.

(d) You also agree to comply with the licenses associated with the Materials you acquire from the Site. You also agree to pass on all license terms and attributions associated with the objects as required by the licenses associated with those Materials.

(e) If you make use of our APIs, and should you wish to acquire all or major portions of the Materials from any individual content provider, you are required to contact that content provider directly.

(f) We reserve the right to monitor usage of our APIs and to discontinue access to the Site by users of the APIs who are determined to be in violation of this Agreement. If you have registered with us, we will make an effort to notify you of any potential violations. In addition to monitoring, we may maintain records of API use and information about the requestor.

Introduction / Concepts

Getting in touch

For any question about the API, please head to the #diveboard channel in irc.freenode.net.

General Idea

The API was designed to be as generic as possible but still enabling complex and powerful actions.

The API is very (maybe too) close to the actual DB model, and was mostly built as an abstraction layer handling permission and CRUD functions. You can list objects (dives, spots, … ) update them (if you have the rights to), create new object.... and even create nested objects within a single API call.

How to test

For testing purposes, you may want to try and use our staging environment. Beware that this environment has always new features, but it should still be stable.

Please do not make load testing with either environment without checking with us that it’s OK to do so !

Environment	Usage	URL
Production	Real life environment	http://www.divaboard.com
Staging	Next version testing	http://stage.diveboard.com

APIs

Presentation

The APIs can be separated into 4 different kinds :

1. administrative calls (login)

2. object manipulation calls (read, create, update, delete dives, …)

3. search (spots, …)

4. file upload (profiles, pictures)

All POST call should send the parameters as "Content-Type: multipart/form-data;"

The ‘Walkthrough’ section gives examples on how to use the different APIs.

For privacy issues, all calls should always be done over HTTPS.

Administrative functions

Login with Facebook

Presentation

This call logs in a user by checking fbtoken + fbid and issues a token which should be used to make further API calls. The issued token has a 1 month validity by default, but please refer to the expiration string to be sure of that.

If the user is not registered on Diveboard, it will create an account linked with facebook authentication.

URL

HTTP method	URL
POST	/api/login_fb

HTTP parameters

Name	Type / Format	Mandatory/Optional	Null?	Description
fbid	STRING	M	N	User's Facebook ID
fbtoken	STRING	M	N	User's Facebook Token (as given by facebook)
apikey	STRING	M	N	the application's API key

Output

The body of the response is a JSON string, which contains a Hash. The attributes of this Hash are described in the table here.

Name	Type / Format	Mandatory/Optional	Null?	Description
success	BOOLEAN	M	N	false only if a big error
error	STRING XXX	O	N	string defining the error (only present if success==false)
error_tag	String	O	N	id of the error (only present if success==false) This id should be provided when available to report bugs to Diveboard.
token	String	M	N	string with the authentication token to use
vanity_url_defined Deprecated
expiration	STRING "2012-05-02T14:48:09Z"	M	N	Date when the token expires - 1day (prevent all timezone craze)
id	STRING	M	N	Shaken ID of the new user
units Deprecated
preferred_units	UNITS Object	M	N	User preference about units
new_account	BOOLEAN	M	N	True if an account was created
user	USER Object	M	N	The User object rendered with a "private" flavour

Login with Email/Password

Presentation

This call logs in a user by checking the email and password, and issues a token which should be used to make further API calls. The issued token has a 1 month validity by default, but please refer to the expiration string to be sure of that.

If the user is not registered on Diveboard, it will create an account. In this case, the ‘vanity_url_defined’ attribute will be set to ‘true’ and you should make a call to ‘api/register_vanity_url’ to finish the registration process.

URL

HTTP method	URL
POST	/api/login_email

HTTP parameters

Name	Type / Format	Mandatory/Optional	Null?	Description
email	STRING	M	N	User's email
password	STRING	M	N	User’s plaintext password
apikey	STRING	M	N	the application's API key

Output

The body of the response is a JSON string, which contains a Hash. The attributes of this Hash are described in the table here.

Name	Type / Format	Mandatory/Optional	Null?	Description
success	BOOLEAN	M	N	false only if a big error
error	STRING XXX	O	N	string defining the error (only present if success==false)
error_tag	String	O	N	id of the error (only present if success==false) This id should be provided when available to report bugs to Diveboard.
units Deprecated	JSON Object	O	Y
preferred_units	UNITS Object	M	N	User preference about units
token	String	M	N	string with the authentication token to use
expiration	STRING "2012-05-02T14:48:09Z"	M	N	Date when the token expires - 1day (prevent all timezone craze)
id	STRING	M	N	id of the user
new_account	BOOLEAN	M	N	True if an account was created
user	USER Object	M	N	The User object rendered with a "private" flavour

Change a vanity_url

Presentation

This call will change a vanity url of a user.

URL

HTTP method	URL
POST	/api/register_vanity_url

HTTP parameters

Name	Type / Format	Mandatory/Optional	Null?	Description
token	STRING	M	N	User’s authentication token
vanity_url	STRING	M	N	Chosen vanity URL
apikey	STRING	M	N	the application's API key

Output

The body of the response is a JSON string, which contains a Hash. The attributes of this Hash are described in the table here.

Name	Type / Format	Mandatory/Optional	Null?	Description
success	BOOLEAN	M	N	false only if a big error
error	STRING	O	N	string defining the error (only present if success==false)
error_tag	String	O	N	id of the error (only present if success==false) This id should be provided when available to report bugs to Diveboard.

Object Manipulation

Presentation

The set of API for object manipulation uses the same logic for all objects. It is based on JSON objects.

When updating an object, some attributes may be rejected while others will be accepted. As a general rule, all the valid changes will be taken into account and applied, and only the invalid changes will be discarded. This mean that if you’re updating both the duration and the gears of a dive with a correct duration but an invalid gear, the change on duration will be applied but the change of gear will not be applied. The answer will notify you of the error on the gear update.

To have the details of the objects that can be passed, please refer to the section "Objects". For a better understanding of how to manipulate these calls, you should have a look at the "Walkthrough" section.

URL

Type of object	HTTP method	URL
user	read : POST create : POST update : POST delete : not available	/api/V2/user /api/V2/user/_id_
dive	read : POST create : POST update : POST delete : DELETE	/api/V2/dive /api/V2/dive/_id_
spot	read : POST create : POST update : POST delete : not available	/api/V2/spot /api/V2/spot/_id_
shop	read : POST create : POST update : POST delete : not available	/api/V2/shop /api/V2/shop/_id_
review	read : POST create : POST update : POST delete : DELETE	/api/V2/review /api/V2/review/_id_
notif	read : POST create : POST update : POST delete : DELETE	/api/V2/notif /api/V2/notif/_id_

HTTP parameters

Name	Type / Format	Mandatory/Optional	Null?	Description
flavour	string	O	Y	One or several flavours separated by comma. This will command the level of detail for each object in the response. e.g. "private,dive_profile"
arg	JSON STRING of OBJECT or JSON STRING of ARRAY of OBJECT	M	N	JSON string describing the object to read, create, update or delete.
auth_token	STRING	O	N	authentication string
apikey	STRING	M	N	API key

Output

The body of the response is a JSON string, which contains a Hash. The attributes of this Hash are described in the table here.

Name	Type / Format	Mandatory/Optional	Null?	Description
success	BOOLEAN	M	N	false only if a big error
error	ARRAY of STRING or..... ARRAY of OBJECT ERROR	O	N	errors can be reported even if success is true. For example, when updating an object, some attributes may be rejected while others will be accepted.
result	OBJECT	O	Y	only if no error
error_tag	String	O	N	id of the error (only present if success==false) This id should be provided when available to report bugs to Diveboard.

Examples

Here are a few simple example calls to read users detail and create a new dive. Please refer to the "Walkthrough" section for more complex examples.

To get the details of a user :

REQUEST	curl -X GET "http://www.diveboard.com/api/V2/user/48" -F "apikey=xxXXX6XXX6XxxxX6XXXX"
RESPONSE	{"success":true,"error":[],"result":{"id":48,"vanity_url":"pascal","nickname":"Pascal", …................ }}

To get more detail for a user, use a different flavour (cf. the object section to get the list of values per parameter) :

REQUEST	curl "http://www.diveboard.com/api/V2/user" -F 'arg={"id":48}' -F 'flavour=private' -F 'auth_token=ip4rHSSD9/diOWR3szonh7ikbhl0k9g/UgMSTBfjb00=' -F "apikey=xxXXX6XXX6XxxxX6XXXX"
RESPONSE	{"success":true,"error":[],"result":{"flavour":"private","id":48,"vanity_url":"pascal","nickname":"Pascal", "pict":true, …................ }}

To create a new element, just send the data without specifying an id. You will get the id in the returned object detail :

REQUEST

curl -s "http://l.dev.diveboard.com/api/V2/dive" -F 'auth_token=UEEnVPDmErqKIKhI952vcQMnU1qbTQ/WxlXsnXUNBoY=' -F "apikey=j9icv6zlgwq9" -F 'arg={"user_id": 12885, "duration": 90, "maxdepth":40, "time_in": "2011-10-16T09:40:00Z", "spot": {"name":"Blue hole", "country_code":"MT","location":{"name":"Gozo"}, "region":{"name":"Mediterranean Sea"}}}'

RESPONSE

{"success":true,"error":[],"result":{"class":"Dive","flavour":"public","id":31722,"shaken_id":"D6fQS5L","time_in":"2011-10-16T09:40:00Z","duration":90,"maxdepth":40.0,"user_id":12885,"spot_id":21481,"temp_surface":null,"temp_bottom":null,"privacy":0,"weights":null,"safetystops":null,"divetype":[],"favorite":null,"buddy":[],"visibility":null,"trip_name":null,"water":null,"altitude":0,"fullpermalink":"http://l.dev.diveboard.com//D6fQS5L","permalink":"//D6fQS5L","complete":true,"thumbnail_image_url":"http://l1.dev.diveboard.com/map_images/map_21481.jpg","thumbnail_profile_url":null,"guide":null,"shop_id":null,"notes":null,"public_notes":null,"diveshop":null,"current":null,"species":[],"gears":[],"user_gears":[],"dive_gears":[],"date":"2011-10-16","time":"09:40"},"user_authentified":true}

To update an element, you only need to provide the id of the element you wish to update and the parameters that need to be updated. The other details will not be changed.

REQUEST

curl "http://www.diveboard.com/api/V2/dive" -F "auth_token=ip4rHSSD9/diOWR3szonh7ikbhl0k9g/UgMSTBfjb00=" -F "apikey=xxXXX6XXX6XxxxX6XXXX" -F 'arg={"id":10306,"duration":120}'

RESPONSE

{"success":true,"error":[],"result":{"class":"Dive","flavour":"public","id":10306,"time_in":"2011-10-16T09:40:00Z","duration":120,"maxdepth":"40.0","user_id":32,"spot_id":1843,"temp_surface":null,"temp_bottom":null,"privacy":0,"weights":null,"safetystops":null,"divetype":[],"favorite":null,"buddy":[],"visibility":null,"trip_name":null,"water":null,"altitude":0,"fullpermalink":"http://www.diveboard.com/duncan.farthing/10306","complete":false,"thumbnail_image_url":"http://www.diveboard.com/map_images/map_1.jpg","thumbnail_profile_url":null,"species":[],"guide":null,"shop_id":null,"notes":null,"public_notes":null,"diveshop":null,"gears":[],"user_gears":[],"dive_gears":[],"date":"2011-10-16","time":"09:40"}}

Search

Spots

Presentation

This API will let you search spot base from a lat/long OR a name.

If an auth_token and apikey is passed, user will be logged and will access his private spots (if any)

URL

HTTP method	URL
GET/POST	/api/search/spot

HTTP parameters

Name	Type / Format	Mandatory/Optional	Null?	Description
q	STRING	O	N	name to search
lat	FLOAT	O	N	latitude in degrees
lng	FLOAT	O	N	longitude in degrees
apikey	STRING	M	N	Api key
auth_token	STRING	O	N	user auth token

Output

The body of the response is a JSON HASH, which contains an ARRAY of maximum 50 answers. The attributes of this Hash are described in the table here.

Name	Type / Format	Mandatory/Optional	Null?	Description
sucess	BOOLEAN	M	N	true/false
data	JSON ARRAY (see below)	M	N	array of spot data
error	STRING	O	Y	error explained

data :

Name	Type / Format	Mandatory/Optional	Null?	Description
name	STRING	M	N	a formatted name of the spot i.e. "White River (Greece - Cyprus)"
id	INTEGER	M	N	spot ID
data	SPOT object, public flavour	M	N	SPOT Object, public flavour

Species

Presentation

This API will let you search species base for a name or search for family of a given id( ancestors...).

On species search only species are returned (no other taxonrank)

IDs have 2 formats : s-12345 for scientific names and c-12345 for common names … they are STRINGS

URL

HTTP method	URL
POST	/api/fishsearch_extended

HTTP parameters

Name	Type / Format	Mandatory/Optional	Null?	Description
name	STRING	O	N	name to search
id	STRING	O	N	the id of a base species (s-xxxx or c-xxxx)
scope	STRING	O	N	"children", "siblings", "ancestors" for a given id - only works if id is given
page_size	Integer	O	N	number of results per page
page	INTEGER	O	N	page number
apikey	STRING	M	N	Api key

Output

The body of the response is a JSON HASH, which contains an ARRAY of maximum 50 answers. The attributes of this Hash are described in the table here.

Name	Type / Format	Mandatory/Optional	Null?	Description
sucess	BOOLEAN	M	N	true/false
result	JSON ARRAY of SPECIES	M	N	array of spot data
paginate	JSON paginate object	M	N	"paginate":{"next":null,"previous":null,"total":5,"total_pages":1,"current_page":1}
error	STRING	O	Y	error explained

data :

Name	Type / Format	Mandatory/Optional	Null?	Description
id	STRING	M	N	"s-13124" or "c-124214"
sname	STRING	M	N	scientific name
cname	STRING ARRAY	M	Y	list of common names
preferred_name	STRING	M	Y	Preferred common name
picture	STRING	M	Y	link to a picture
bio	STRING	M	Y	Biological info from EOL
rank	STRING	M	N	taxon rank
category	STRING	M	N	what family the fish belong to
data	SPOT object, public flavour	M	N	SPOT Object, public flavour

Uploading files

Profile upload

Presentation

This API needs to be used before assigning or creating a dive with a given profile. As of version 0.1, it supports UDCF and DL7 file formats.

URL

HTTP method	URL
POST	/api/upload_profile

HTTP parameters

Name	Type / Format	Mandatory/Optional	Null?	Description
token	STRING	M	N	token for the user
filename	BINARY	M	N	content of the file
apikey	STRING	M	N	Api key

Output

The body of the response is a JSON string, which contains a Hash. The attributes of this Hash are described in the table here.

Name	Type / Format	Mandatory/Optional	Null?	Description
success	BOOLEAN	M	N
error	STRING	O	N
nbdives	INTEGER	M	N	number of dives found in the uploaded file
dive_summary	ARRAY of HASH	M	N	For each dive found in the file, a summary of the dive is reported in a hash containing the following keys : - number: 0 : the number of the dive in the file (if file has many dives) - date: "2010-07-28" : date of the dive as in the file - time: "21:18" : the time in HH:MM - duration: 77 : in minutes - max_depth: 7.9 : in meters - maxtemp: 25 : in celsius - mintemp: 2 : in celsius - newdive: true : does it look like a new dive or a profile the user already has uploaded ?
fileid	INTEGER	M	N	ID of the uploaded file

Picture upload

Presentation

‘TODO XXX’

URL

HTTP method	URL
POST	/api/picture/upload

HTTP parameters

Name	Type / Format	Mandatory/Optional	Null?	Description
qqfile

Output

The body of the response is a JSON string, which contains a Hash. The attributes of this Hash are described in the table here.

Name	Type / Format	Mandatory/Optional	Null?	Description

WALKTHROUGH

Logging in

Example to log in a user with his facebook ID and facebook token

curl -s "http://stage.diveboard.com/api/login_fb" -F "fbid=100004637132223" -F "fbtoken=AAABzYDF4nt0BAL1e0gF86RRV4xoRu2rZAmXxJerM4IJLbXLZBNm2KiVXYD7ZBakiNgreUP5yPDMwqpYIhKnoNnIK" -F "apikey=hwkzq4rhw9lq"

{"success":true,"token":"wtV6sxKrMdXXBV+dVrqhJs936KKrq0TQBw2toWjM+Lk=","expiration":"2012-11-26T19:57:44Z","vanity_url_defined":false,"units":{"distance":"Km","weight":"Kg","temperature":"C","pressure":"bar"},"id":"U3T7iSQ"}

Reading an object

To get an object with a given flavour from an id, you need to call the given API and pass as argument only the ‘id’ value in the ‘arg’ hash.

Example to get the basic details for a user

curl -s "http://stage.diveboard.com/api/V2/user/U3T7iSQ" -F "apikey=hwkzq4rhw9lq"

{"success":true,"error":[],"result":{"class":"User","flavour":"public","id":12850,"shaken_id":"U3T7iSQ","vanity_url":null,"qualifications":{},"picture":"http://graph.facebook.com/100004637132223/picture?type=normal","picture_small":"http://graph.facebook.com/100004637132223/picture?type=square","picture_large":"http://graph.facebook.com/100004637132223/picture?type=large","full_permalink":"http://stage.diveboard.com/","total_nb_dives":0,"public_nb_dives":0,"public_dive_ids":[],"nickname":"David Narayanansen"},"user_authentified":false}

Creating an object

Creating an object is similar to updating an object.... but since you don’t know what ‘id’ the object will get, then just don’t supply it ! If everything went correctly, you’ll get the JSON of the object in the response, and you may then get the attributed ‘id’ for further updates.

Example to create a new dive

curl -s "http://stage.diveboard.com/api/V2/dive" -F 'auth_token=wtV6sxKrMdXXBV+dVrqhJs936KKrq0TQBw2toWjM+Lk=' -F "apikey=hwkzq4rhw9lq" -F 'arg={"user_id": "U3T7iSQ", "duration": 90, "maxdepth":40, "time_in": "2011-10-16T09:40:00Z", "spot":{"id":1843}}'

{"success":true,"error":[],"result":{"class":"Dive","flavour":"public","id":31671,"shaken_id":"D3eyz9U","time_in":"2011-10-16T09:40:00Z","duration":90,"maxdepth":40.0,"user_id":12850,"spot_id":1843,"temp_surface":null,"temp_bottom":null,"privacy":0,"weights":null,"safetystops":null,"divetype":[],"favorite":null,"buddy":[],"visibility":null,"trip_name":null,"water":null,"altitude":0,"fullpermalink":"http://stage.diveboard.com//D3eyz9U","permalink":"//D3eyz9U","complete":true,"thumbnail_image_url":"http://stage.diveboard.com/map_images/map_1843.jpg","thumbnail_profile_url":null,"guide":null,"shop_id":null,"notes":null,"public_notes":null,"diveshop":null,"current":null,"species":[],"gears":[],"user_gears":[],"dive_gears":[],"date":"2011-10-16","time":"09:40"},"user_authentified":true}

Updating part of an object

To update some attributes from an object, you need to pass the ‘id’ of the object and then include in the ‘arg’ hash only the attributes you wish to modify. Please note that if you include one attribute with a ‘null’ value, we will try to overwrite that attribute in the database to null. So be careful to send only the attributes you wish to update, or make sure you send the exact same value.

Example to update the nickname of a user

curl -s "http://stage.diveboard.com/api/V2/user" -F 'arg={"id":"12850", "nickname":"New Nick"}' -F 'auth_token=wtV6sxKrMdXXBV+dVrqhJs936KKrq0TQBw2toWjM+Lk=' -F "apikey=hwkzq4rhw9lq"

{"success":true,"error":[],"result":{"class":"User","flavour":"public","id":12850,"shaken_id":"U3T7iSQ","vanity_url":null,"qualifications":{},"picture":"http://graph.facebook.com/100004637132223/picture?type=normal","picture_small":"http://graph.facebook.com/100004637132223/picture?type=square","picture_large":"http://graph.facebook.com/100004637132223/picture?type=large","full_permalink":"http://stage.diveboard.com/","total_nb_dives":0,"public_nb_dives":0,"public_dive_ids":[],"nickname":"New Nick"},"user_authentified":true}

Example to update both the duration and the depth on a dive

curl -s "http://stage.diveboard.com/api/V2/dive" -F 'auth_token=wtV6sxKrMdXXBV+dVrqhJs936KKrq0TQBw2toWjM+Lk=' -F "apikey=hwkzq4rhw9lq" -F 'arg={"id": "31671", "duration": 50, "maxdepth":50}'

{"success":true,"error":[],"result":{"class":"Dive","flavour":"public","id":31671,"shaken_id":"D3eyz9U","time_in":"2011-10-16T09:40:00Z","duration":50,"maxdepth":50.0,"user_id":12850,"spot_id":1843,"temp_surface":null,"temp_bottom":null,"privacy":0,"weights":null,"safetystops":null,"divetype":[],"favorite":null,"buddy":[],"visibility":null,"trip_name":null,"water":null,"altitude":0,"fullpermalink":"http://stage.diveboard.com//D3eyz9U","permalink":"//D3eyz9U","complete":true,"thumbnail_image_url":"http://stage.diveboard.com/map_images/map_1843.jpg","thumbnail_profile_url":null,"guide":null,"shop_id":null,"notes":null,"public_notes":null,"diveshop":null,"current":null,"species":[],"gears":[],"user_gears":[],"dive_gears":[],"date":"2011-10-16","time":"09:40"},"user_authentified":true}

Example to add a dive profile to a dive

curl -s "http://stage.diveboard.com/api/V2/dive" -F 'auth_token=z61mYD1bUa7xCJBAfOqcBmy8I/rGGpkMKrQS5dOaHio=' -F "apikey=76soje9nvcne" -F 'flavour=public_with_profile' -F 'arg={"id": "31678", "raw_profile":[{"seconds":0, "depth":0}, {"seconds":30, "depth":3}, {"seconds":60, "depth":5}, {"seconds":90, "depth":10}, {"seconds":2900, "depth":10}, {"seconds":3000, "depth":0} ]}'

{"success":true,"error":[],"result":{"class":"Dive","flavour":"public_with_profile","id":31678,"shaken_id":"D44ZZwl","time_in":"2011-10-16T09:40:00Z","duration":50,"maxdepth":50.0,"user_id":12855,"spot_id":1843,"temp_surface":null,"temp_bottom":null,"privacy":0,"weights":null,"safetystops":null,"divetype":[],"favorite":null,"buddy":[],"visibility":null,"trip_name":null,"water":null,"altitude":0,"fullpermalink":"http://stage.diveboard.com//D44ZZwl","permalink":"//D44ZZwl","complete":true,"thumbnail_image_url":"http://stage.diveboard.com/map_images/map_1843.jpg","thumbnail_profile_url":"http://stage.diveboard.com//31678/profile.png?g=small_or&u=m","guide":null,"shop_id":null,"notes":null,"public_notes":null,"diveshop":null,"current":null,"species":[],"gears":[],"user_gears":[],"dive_gears":[],"date":"2011-10-16","time":"09:40","raw_profile":[{"class":"ProfileData","flavour":"public","seconds":0,"depth":0.0,"current_water_temperature":null,"main_cylinder_pressure":null,"heart_beats":null,"deco_violation":false,"deco_start":false,"ascent_violation":false,"bookmark":false,"surface_event":false},{"class":"ProfileData","flavour":"public","seconds":30,"depth":3.0,"current_water_temperature":null,"main_cylinder_pressure":null,"heart_beats":null,"deco_violation":false,"deco_start":false,"ascent_violation":false,"bookmark":false,"surface_event":false},{"class":"ProfileData","flavour":"public","seconds":60,"depth":5.0,"current_water_temperature":null,"main_cylinder_pressure":null,"heart_beats":null,"deco_violation":false,"deco_start":false,"ascent_violation":false,"bookmark":false,"surface_event":false},{"class":"ProfileData","flavour":"public","seconds":90,"depth":10.0,"current_water_temperature":null,"main_cylinder_pressure":null,"heart_beats":null,"deco_violation":false,"deco_start":false,"ascent_violation":false,"bookmark":false,"surface_event":false},{"class":"ProfileData","flavour":"public","seconds":2900,"depth":10.0,"current_water_temperature":null,"main_cylinder_pressure":null,"heart_beats":null,"deco_violation":false,"deco_start":false,"ascent_violation":false,"bookmark":false,"surface_event":false},{"class":"ProfileData","flavour":"public","seconds":3000,"depth":0.0,"current_water_temperature":null,"main_cylinder_pressure":null,"heart_beats":null,"deco_violation":false,"deco_start":false,"ascent_violation":false,"bookmark":false,"surface_event":false}]},"user_authentified":true}

Adding or removing a pre-existing element in a list

As for the standard attribute update, you need to pass the ‘id’ of the object and then include in the ‘arg’ hash only the attributes you wish to modify. Now, for lists, you need to supply the whole list of elements. For existing objects, you don’t need to send back the whole details of the sub-objects : just their ‘id’ is sufficient. This means for example that to add an element you need to supply the previous list plus the new element.

Example to add a gear to a dive

curl -s "http://stage.diveboard.com/api/V2/user" -F 'auth_token=wtV6sxKrMdXXBV+dVrqhJs936KKrq0TQBw2toWjM+Lk=' -F 'flavour=private' -F "apikey=hwkzq4rhw9lq" -F 'arg={"id":"12850", "user_gears": [{"category":"Computer", "model":"Vyper", "manufacturer":"Suunto"}]}'

{"success":true,"error":[],"result":{"class":"User","flavour":"private","id":12850,"shaken_id":"U3T7iSQ","vanity_url":null,"qualifications":{},"picture":"http://graph.facebook.com/100004637132223/picture?type=normal","picture_small":"http://graph.facebook.com/100004637132223/picture?type=square","picture_large":"http://graph.facebook.com/100004637132223/picture?type=large","full_permalink":"http://stage.diveboard.com/","total_nb_dives":1,"public_nb_dives":1,"public_dive_ids":[31671],"nickname":"New Nick","dan_data":null,"storage_used":{"dive_pictures":0,"monthly_dive_pictures":0,"orphan_pictures":0,"all_pictures":0},"quota_type":"per_month","quota_limit":524288000,"all_dive_ids":[31671],"pict":false,"advertisements":[],"ad_album_id":30711,"user_gears":[{"class":"UserGear","flavour":"private","category":"Computer","id":2106,"manufacturer":"Suunto","model":"Vyper","featured":null,"acquisition":null,"last_revision":null,"reference":null,"auto_feature":"never"}]},"user_authentified":true}

Example to remove all user_gears from a dive

curl -s "http://stage.diveboard.com/api/V2/user" -F 'auth_token=wtV6sxKrMdXXBV+dVrqhJs936KKrq0TQBw2toWjM+Lk=' -F 'flavour=private' -F "apikey=hwkzq4rhw9lq" -F 'arg={"id":"12850", "user_gears": []}'

{"success":true,"error":[],"result":{"class":"User","flavour":"private","id":12850,"shaken_id":"U3T7iSQ","vanity_url":null,"qualifications":{},"picture":"http://graph.facebook.com/100004637132223/picture?type=normal","picture_small":"http://graph.facebook.com/100004637132223/picture?type=square","picture_large":"http://graph.facebook.com/100004637132223/picture?type=large","full_permalink":"http://stage.diveboard.com/","total_nb_dives":1,"public_nb_dives":1,"public_dive_ids":[31671],"nickname":"New Nick","dan_data":null,"storage_used":{"dive_pictures":0,"monthly_dive_pictures":0,"orphan_pictures":0,"all_pictures":0},"quota_type":"per_month","quota_limit":524288000,"all_dive_ids":[31671],"pict":false,"advertisements":[],"ad_album_id":30711,"user_gears":[]},"user_authentified":true}

Deleting an object

To delete an object, the HTTP method to use is DELETE

Example to delete a dive

curl -X DELETE -s "http://stage.diveboard.com/api/V2/dive/31671" -F 'auth_token=wtV6sxKrMdXXBV+dVrqhJs936KKrq0TQBw2toWjM+Lk=' -F "apikey=hwkzq4rhw9lq"

{"success":true,"result":null,"error":[],"user_authentified":true}

Creating several objects of the same type at the same time

In order to make batch creation easier, the ‘arg’ parameter may accept an array of Hash that all describe the same type of objects.

Example to create 2 different dives at the same time

curl -s "http://stage.diveboard.com/api/V2/dive" -F 'auth_token=wtV6sxKrMdXXBV+dVrqhJs936KKrq0TQBw2toWjM+Lk=' -F "apikey=hwkzq4rhw9lq" -F 'arg=[{"user_id": "U3T7iSQ", "duration": 90, "maxdepth":40, "time_in": "2011-10-16T09:40:00Z", "spot":{"id":1843}},{"user_id": "U3T7iSQ", "duration": 50, "maxdepth":50, "time_in": "2011-10-17T09:40:00Z", "spot":{"id":1843}}]'

{"success":true,"error":[],"result":[{"class":"Dive","flavour":"public","id":31672,"shaken_id":"D3iddpx","time_in":"2011-10-16T09:40:00Z","duration":90,"maxdepth":40.0,"user_id":12850,"spot_id":1843,"temp_surface":null,"temp_bottom":null,"privacy":0,"weights":null,"safetystops":null,"divetype":[],"favorite":null,"buddy":[],"visibility":null,"trip_name":null,"water":null,"altitude":0,"fullpermalink":"http://stage.diveboard.com//D3iddpx","permalink":"//D3iddpx","complete":true,"thumbnail_image_url":"http://stage.diveboard.com/map_images/map_1843.jpg","thumbnail_profile_url":null,"guide":null,"shop_id":null,"notes":null,"public_notes":null,"diveshop":null,"current":null,"species":[],"gears":[],"user_gears":[],"dive_gears":[],"date":"2011-10-16","time":"09:40"},{"class":"Dive","flavour":"public","id":31673,"shaken_id":"D3mIIWQ","time_in":"2011-10-17T09:40:00Z","duration":50,"maxdepth":50.0,"user_id":12850,"spot_id":1843,"temp_surface":null,"temp_bottom":null,"privacy":0,"weights":null,"safetystops":null,"divetype":[],"favorite":null,"buddy":[],"visibility":null,"trip_name":null,"water":null,"altitude":0,"fullpermalink":"http://stage.diveboard.com//D3mIIWQ","permalink":"//D3mIIWQ","complete":true,"thumbnail_image_url":"http://stage.diveboard.com/map_images/map_1843.jpg","thumbnail_profile_url":null,"guide":null,"shop_id":null,"notes":null,"public_notes":null,"diveshop":null,"current":null,"species":[],"gears":[],"user_gears":[],"dive_gears":[],"date":"2011-10-17","time":"09:40"}],"user_authentified":true}

Updating several objects of the same type at the same time

An array within ‘arg’ can also be used to update several objects of the same type.

Example to update 2 different dives at the same time

curl -s "http://stage.diveboard.com/api/V2/dive" -F 'auth_token=wtV6sxKrMdXXBV+dVrqhJs936KKrq0TQBw2toWjM+Lk=' -F "apikey=hwkzq4rhw9lq" -F 'arg=[{"id":31672,"duration": 91},{"id":31673,"maxdepth":51}]'

{"success":true,"error":[],"result":[{"class":"Dive","flavour":"public","id":31672,"shaken_id":"D3iddpx","time_in":"2011-10-16T09:40:00Z","duration":91,"maxdepth":40.0,"user_id":12850,"spot_id":1843,"temp_surface":null,"temp_bottom":null,"privacy":0,"weights":null,"safetystops":null,"divetype":[],"favorite":null,"buddy":[],"visibility":null,"trip_name":null,"water":null,"altitude":0,"fullpermalink":"http://stage.diveboard.com//D3iddpx","permalink":"//D3iddpx","complete":true,"thumbnail_image_url":"http://stage.diveboard.com/map_images/map_1843.jpg","thumbnail_profile_url":null,"guide":null,"shop_id":null,"notes":null,"public_notes":null,"diveshop":null,"current":null,"species":[],"gears":[],"user_gears":[],"dive_gears":[],"date":"2011-10-16","time":"09:40"},{"class":"Dive","flavour":"public","id":31673,"shaken_id":"D3mIIWQ","time_in":"2011-10-17T09:40:00Z","duration":50,"maxdepth":51.0,"user_id":12850,"spot_id":1843,"temp_surface":null,"temp_bottom":null,"privacy":0,"weights":null,"safetystops":null,"divetype":[],"favorite":null,"buddy":[],"visibility":null,"trip_name":null,"water":null,"altitude":0,"fullpermalink":"http://stage.diveboard.com//D3mIIWQ","permalink":"//D3mIIWQ","complete":true,"thumbnail_image_url":"http://stage.diveboard.com/map_images/map_1843.jpg","thumbnail_profile_url":null,"guide":null,"shop_id":null,"notes":null,"public_notes":null,"diveshop":null,"current":null,"species":[],"gears":[],"user_gears":[],"dive_gears":[],"date":"2011-10-17","time":"09:40"}],"user_authentified":true}

Updating recursively several objects at the same time

Now comes the tricky part. When you update an object (e.g. a dive) you can at the same time create or update another object that is referred by this dive. For that, just add the attributes you would like to change along with the ‘id’ attribute that was already provided.

Example to update recursively a dive and a user_gear in the same call

curl -s "http://stage.diveboard.com/api/V2/dive" -F 'auth_token=wtV6sxKrMdXXBV+dVrqhJs936KKrq0TQBw2toWjM+Lk=' -F "apikey=hwkzq4rhw9lq" -F 'flavour=private' -F 'arg={"id":31672, "duration":55, "user_gears":[{"id":2106, "model":"Vyper Air"}]}'

{"success":true,"error":[],"result":{"class":"Dive","flavour":"private","id":31672,"shaken_id":"D3iddpx","time_in":"2011-10-16T09:40:00Z","duration":55,"maxdepth":40.0,"user_id":12850,"spot_id":1843,"temp_surface":null,"temp_bottom":null,"privacy":0,"weights":null,"safetystops":null,"divetype":[],"favorite":null,"buddy":[],"visibility":null,"trip_name":null,"water":null,"altitude":0,"fullpermalink":"http://stage.diveboard.com//D3iddpx","permalink":"//D3iddpx","complete":true,"thumbnail_image_url":"http://stage.diveboard.com/map_images/map_1843.jpg","thumbnail_profile_url":null,"guide":null,"shop_id":null,"notes":null,"public_notes":null,"diveshop":null,"current":null,"species":[],"gears":[{"class":"UserGear","flavour":"private","category":"Computer","id":2106,"manufacturer":"Suunto","model":"Vyper Air","featured":false,"acquisition":null,"last_revision":null,"reference":null,"auto_feature":"never"}],"user_gears":[{"class":"UserGear","flavour":"private","category":"Computer","id":2106,"manufacturer":"Suunto","model":"Vyper Air","featured":false,"acquisition":null,"last_revision":null,"reference":null,"auto_feature":"never"}],"dive_gears":[],"date":"2011-10-16","time":"09:40","dan_data":null,"dan_data_sent":null,"storage_used":0,"profile_ref":null},"user_authentified":true}

Creating recursively objects

This type of call can be very useful to prevent chaining multiple calls. In the example below, instead of calling first the API to create a user_gear and making a second call to assign that user_gear to the dive, only one call can do the trick.

Example to create a new user_gear and assigning an existing user_gear to a dive

curl -s "http://stage.diveboard.com/api/V2/dive" -F 'auth_token=wtV6sxKrMdXXBV+dVrqhJs936KKrq0TQBw2toWjM+Lk=' -F "apikey=hwkzq4rhw9lq" -F 'flavour=private' -F 'arg={"id":31672, "user_gears":[{"id":2106}, {"user_id":12850,"category":"Computer","manufacturer":"Mares","model":"Icon HD"}]}'

{"success":true,"error":[],"result":{"class":"Dive","flavour":"private","id":31672,"shaken_id":"D3iddpx","time_in":"2011-10-16T09:40:00Z","duration":91,"maxdepth":40.0,"user_id":12850,"spot_id":1843,"temp_surface":null,"temp_bottom":null,"privacy":0,"weights":null,"safetystops":null,"divetype":[],"favorite":null,"buddy":[],"visibility":null,"trip_name":null,"water":null,"altitude":0,"fullpermalink":"http://stage.diveboard.com//D3iddpx","permalink":"//D3iddpx","complete":true,"thumbnail_image_url":"http://stage.diveboard.com/map_images/map_1843.jpg","thumbnail_profile_url":null,"guide":null,"shop_id":null,"notes":null,"public_notes":null,"diveshop":null,"current":null,"species":[],"gears":[{"class":"UserGear","flavour":"private","category":"Computer","id":2106,"manufacturer":"Suunto","model":"Vyper","featured":false,"acquisition":null,"last_revision":null,"reference":null,"auto_feature":"never"},{"class":"UserGear","flavour":"private","category":"Computer","id":2107,"manufacturer":"Mares","model":"Icon HD","featured":false,"acquisition":null,"last_revision":null,"reference":null,"auto_feature":"never"}],"user_gears":[{"class":"UserGear","flavour":"private","category":"Computer","id":2106,"manufacturer":"Suunto","model":"Vyper","featured":false,"acquisition":null,"last_revision":null,"reference":null,"auto_feature":"never"},{"class":"UserGear","flavour":"private","category":"Computer","id":2107,"manufacturer":"Mares","model":"Icon HD","featured":false,"acquisition":null,"last_revision":null,"reference":null,"auto_feature":"never"}],"dive_gears":[],"date":"2011-10-16","time":"09:40","dan_data":null,"dan_data_sent":null,"storage_used":0,"profile_ref":null},"user_authentified":true}

Uploading a ZXL or UDCF file

This call will let you upload a profile file in a Diveboard supported format (currently DAN DL7 (aka ZXL or ZXU) and UDCF).

The file will be analyzed and stored and as an output you get a list of the dive profiles present in the file in a digested format as well as their id within the file and the file id itself. This can be used to be bound to a dive.

Example to upload a dive profile file (here zxu) and retrieving the file id and the list of dive profiles in the file

$ curl -F "[email protected]" \ -F "token=tnNxf1D169xCB32RGgQx3b3EcQavksyP5A3ssgLtAj4=" \ -F "apikey=7hvvgobT6cnios" \ http://www.diveboard.com/api/upload_profile

{"success":"true","nbdives":"13","dive_summary":[{"number":0,"date":"2004-09-07","time":"18:54","duration":8,"max_depth":60.1,"mintemp":25.0,"maxtemp":0.0,"newdive":true},{"number":1,"date":"2004-09-10","time":"17:29","duration":9,"max_depth":10.0,"mintemp":25.0,"maxtemp":0.0,"newdive":true},{"number":2,"date":"2004-09-10","time":"17:40","duration":11,"max_depth":20.1,"mintemp":26.0,"maxtemp":0.0,"newdive":true},{"number":3,"date":"2004-09-10","time":"17:52","duration":11,"max_depth":30.1,"mintemp":26.0,"maxtemp":0.0,"newdive":true},{"number":4,"date":"2004-09-10","time":"18:05","duration":13,"max_depth":40.1,"mintemp":26.0,"maxtemp":0.0,"newdive":true},{"number":5,"date":"2004-09-10","time":"18:19","duration":13,"max_depth":50.0,"mintemp":26.0,"maxtemp":0.0,"newdive":true},{"number":6,"date":"2004-09-10","time":"18:33","duration":23,"max_depth":60.0,"mintemp":26.0,"maxtemp":0.0,"newdive":true},{"number":7,"date":"2004-12-02","time":"17:05","duration":25,"max_depth":50.0,"mintemp":20.0,"maxtemp":0.0,"newdive":true},{"number":8,"date":"2005-09-25","time":"11:02","duration":52,"max_depth":33.2,"mintemp":17.0,"maxtemp":0.0,"newdive":true},{"number":9,"date":"2006-01-15","time":"13:36","duration":51,"max_depth":38.0,"mintemp":12.0,"maxtemp":0.0,"newdive":true},{"number":10,"date":"2006-07-16","time":"12:10","duration":51,"max_depth":33.0,"mintemp":18.0,"maxtemp":0.0,"newdive":true},{"number":11,"date":"2006-07-16","time":"14:41","duration":63,"max_depth":29.1,"mintemp":19.0,"maxtemp":0.0,"newdive":true},{"number":12,"date":"2006-10-15","time":"12:33","duration":73,"max_depth":26.1,"mintemp":20.0,"maxtemp":0.0,"newdive":true}],"fileid":1333}

Error catching

$ curl http://www.diveboard.com/api/V2/user

{"success":false,"error":[{"error":"What do you want me to do ? you should specify 'arg'","object":null}]}

$ curl "http://www.diveboard.com/api/V2/user?arg=%7Bid:48,nickname:'coucou'%7D&auth_token=ip4rHSSD9/diOWR3szonh7ikbhl0k9g/UgMSTBfjb00=&apikey=xxXXX6XXX6XxxxX6XXXX"

{"success":true,"error":[{"error":"Forbidden","object":{"id":48,"nickname":"coucou"}}],"result":{"class":"User","flavour":"public","id":48,"vanity_url":"pascal","qualifications":{"featured":[{"org":"CMAS","title":"2 stars diver","date":"2011-07-26"},{"org":"PADI","title":"Advanced Open Water","date":"2011-07-25"},{"org":"CMAS","title":"Nitrox","date":"2011-10-17"}],"other":[{"org":"Other","title":"Cayman Island Lionfish Culling License","date":"2011-11-08"},{"org":"CMAS","title":"1 star","date":"2007-06-01"}]},"picture":"http://www.diveboard.com/user_images/48.png","picture_small":"http://www.diveboard.com/user_images/48.png","picture_large":"http://www.diveboard.com/user_images/48.png","full_permalink":"http://www.diveboard.com/pascal","total_nb_dives":66,"public_nb_dives":29,"public_dive_ids":["728","33","34","30","29","28","27","26","25","24","23","22","10305","555","1850","1851","2434","2435","2436","2437","2438","2439","2442","2443","2532","2533","2569","2570","5632"],"nickname":"Pascal"}}

$ curl "http://www.diveboard.com/api/V2/dive?arg=%7Bid:2434, duration:123%7D&auth_token=ip4rHSSD9/diOWR3szonh7ikbhl0k9g/UgMSTBfjb00=&apikey=xxXXX6XXX6XxxxX6XXXX"

{"success":true,"error":[{"error":"Forbidden","object":{"id":2434,"duration":123}}],"result":{"class":"Dive","flavour":"public","id":2434,"time_in":"2011-10-16T09:40:00Z","duration":53,"maxdepth":"20.1","user_id":48,"spot_id":1843,"temp_surface":20.0,"temp_bottom":19.0,"privacy":0,"weights":null,"safetystops":"[]","divetype":["recreational","Autonomy"],"favorite":null,"buddy":[],"visibility":null,"trip_name":"Nitrox training - Marseilles","water":null,"altitude":0,"fullpermalink":"http://www.diveboard.com/pascal/2434","complete":true,"thumbnail_image_url":"http://www.diveboard.com/map_images/map_1843.jpg","thumbnail_profile_url":"http://www.diveboard.com/pascal/2434/profile.png?g=small_or&u=m","species":[],"guide":"","shop_id":812,"notes":null,"public_notes":null,"diveshop":{"name":"ATOLL - DEEP SUB","url":"http://www.atollplongee.com","guide":"","id":812},"gears":[],"user_gears":[],"dive_gears":[],"date":"2011-10-16","time":"09:40"}}

Objects

USER

Parameter	R E A D	W R I T E	Can be nil	Type/Format	Present in flavours	Comments for read	Comments for write
id	X	X		INTEGER	all	the id of the dive to update if absent, a new dive will be created
shaken_id	X			STRING	all	this attribute is a obfuscated version of the id. It will always be the same for a given object.
vanity_url	X	X		STRING	all
qualifications	X			QUALIFICATION Object	all
picture	X			URL	all
picture_small	X			URL	all
picture_large	X			URL	all
full_permalink	X			URL	all	Full direct link to the user’s logbook on Diveboard
permalink	X			URL	all	Relative path to the logbook (e.g. "/toto")
total_nb_dives	X			INTEGER	all	Number of dives including external dives
public_nb_dives	X			INTEGER	all	Number of public dives
public_dive_ids	X			ARRAY of INTEGER	all	List of all the public dive IDs
location	X			STRING	all	2 letters country code of the user in lowercase
nickname	X	X		STRING	all	Main name displayed all over Diveboard
auto_public	X			BOOLEAN	all	Private data, indicates whether the user wants to set the dive as public by default
dan_data	X	X		HASH	private	Private data used to send DAN forms DO NOT USE
storage_used	X			HASH	private	Detail of the storage used on Diveboard (for pictures mainly) DO NOT USE
quota_type	X			STRING	private	Storage limit type DO NOT USE
quota_limit	X			INTEGER	private	Storage limit DO NOT USE
all_dive_ids	X			ARRAY of INTEGER	private	List of all dives for this user, including private dives
pict	X			BOOLEAN	private	Does the user have a custom picture DO NOT USE
advertisements	X			ARRAY	private	DO NOT USE
ad_album_id	X			INTEGER	private	DO NOT USE
user_gears	X	X		ARRAY of USER_GEAR objects	private	The gear owned by the user that will be used on various dives
about		X				DO NOT USE
email		X				DO NOT USE
contact_email		X				DO NOT USE
location		X			all	Country indicator
settings		X				DO NOT USE
total_ext_dives	X	X		INTEGER	private	Number of dives not on Diveboard, so that total_nb_dives reflects the real number of dives of the user
dives		X
wallet_pictures	X			ARRAY of PICTURE objects	private	gives an array of Picture objects in user wallet
wallet_pictures_id		X		ARRAY OF INTEGER	private	Sets the array of ids of pictures in user wallet

QUALIFICATION OBJECT

Parameter	Can be nil	Type/Format	Comments
featured	NO	ARRAY OF QUALIF_DETAIL	List of qualifications that will appear on the profile
other	NO	ARRAY OF QUALIF_DETAIL	List of qualifications that will only appear on the user’s logbook cover

QUALIF_DETAIL Object

Parameter	Can be nil	Type/Format	Comments
org	NO	STRING	Certification Organisation
title	NO	STRING	Title of the certification
date	NO	STRING YYYY-MM-DD	Date of certification

EXTERNAL USER

Parameter	R E A D	W R I T E	Can be nil	Type/Format	Present in flavours	Comments for read	Comments for write
id	X	X		INTEGER	all	the id of the external user object to update if absent, a new object will be created
nickname	X	X	X	STRING	all	Nickname of the person
picture	X		X	URL	all	standard version of the user’s picture if available	for setting this attribute for non-facebook users, use the attribute picturl
picture_small	X		X	URL	all	small version of the user’s picture if available	for setting this attribute for non-facebook users, use the attribute picturl
picture_large	X		X	URL	all	large version of the user’s picture if available	for setting this attribute for non-facebook users, use the attribute picturl
picturl		X	X	URL			permanent URL to the picture of the user (external url possible, should not be used for facebook users)
fb_id	X	X	X	INTEGER	private	Facebook ID
email	X	X	X	TEXT	private	User’s email address

DIVE

Parameter	R E A D	W R I T E	Can be nil	Type/Format	Present in flavours	Comments for read	Comments for write
id	X	X		INTEGER	all	the id of the dive to update if absent, a new dive will be created
shaken_id	X			STRING	all	this attribute is a obfuscated version of the id. It will always be the same for a given object.
user_id	X	X		INTEGER	all	id of the dive’s owner	id of the dive’s owner
spot	X	X		SPOT object	mobile		The spot tied to this dive - either an existing spot or a new one if no spot is used, MUST use the spot id 1 (sorry) {id = 1}
spot_id	X			INTEGER	all
time_in	X	X		DATETIME	all	"YYYY-MM-DD HH:MM:SS" when diver entered the sea in local time	"YYYY-MM-DD HH:MM:SS" when diver entered the sea in local time
maxdepth	X	X		FLOAT	all	in meters	in meters
duration	X	X		INTEGER	all	in minutes	in minutes
temp_surface	X	X	X	FLOAT	all	Temperature of the water at the surface in celsius	Temperature of the water at the surface in celsius
temp_bottom	X	X	X	FLOAT	all	Temperature of the water at the bottom in celsius	Temperature of the water at the bottom in celsius
privacy	X	X	X	INTEGER	all	1 = dive is private, 0 = dive is public	1 = dive is private, 0 = dive is public
weights	X	X	X	FLOAT	all	in kg	in kg
safetystops	X	X	X	JSON of ARRAY of SAFETYSTOP	all	the list of safety stops e.g: [["6","3"],["3","3"]]	the list of safety stops
divetype	X	X	X	ARRAY of STRINGS	all	the list of the dive types done - strings are free fields e.g: ["training","deep dive","wreck"]	the list of the dive types done - strings are free fields e.g: ["training","deep dive","wreck"]
favorite	X	X	X	BOOLEAN	all	false or null = dive is not in the favorite set true= dive is in the favorite set	false = dive is not in the favorite set true= dive is in the favorite set
buddies		X	X	ARRAY of USER and/or EXTERNAL_USER objects	all
buddies	X			ARRAY of BUDDY objects	all
visibility	X	X	X	STRING	all	string taken in : 'bad','average','good','excellent'	string taken in : 'bad','average','good','excellent'
trip_name	X	X	X	STRING	all	Maximum 255 characters, free field	Maximum 255 characters, free field
water	X	X	X	STRING	all	string taken in : 'salt','fresh'	string taken in : 'salt','fresh'
current	X	X	X	STRING	all	string taken in : 'none','light','medium','strong','extreme'	string taken in : 'none','light','medium','strong','extreme'
altitude	X	X	X	FLOAT	all	in meters	in meters
fullpermalink	X			URL	all	direct full url to the dive (including http://xxx.diveboard.com/....)
permalink	X			STRING	all	DEPRECATED path to the dive (without the leading http://xxx.diveboard.com)
complete	X			BOOL	all	true if the dive could be made public (i.e. has at least a spot, max depth & duration)
thumbnail_image_url	X			STRING	all	url to a square thumbnail image representing the dive (128x128)
thumbnail_profile_url	X		X	STRING	all	url to a thumbnail representing the dive profile data graph
species	X	X	X	ARRAY of SPECIES	all	array of the species spotted during the dive - only "s-XXXXX" (c- gets replaced by its s-) species => [{:id => "s-1234"}, {:id => "s-2345"}]	array of the species spotted during the dive as scientific name "s-XXXX" or common name "c-XXXX" species => [{:id => "s-1234"}, {:id => "s-2345"}]
guide	X	X	X	STRING	all	name of the guide	name of the guide
shop	X	X	X	SHOP object	all		the dive shop the user dived with, when the shop already exists in Diveboard database
shop_id	X		X	INTEGER	all	id of the dive shop used in that dive
diveshop		X	X	HASH			DEPRECATED A Hash containing the following key, to enable a free fill in when a diveshop does not exists in Diveboard database : - name : name of the shop - url : url of the shop - country : country code - town : town name
diveshop	X		X	HASH	all	DEPRECATED A Hash containing some of the following key. It is constructed based on the ‘diveshop’ value, and overwritten with the values of ‘shop’ and ‘guide’ if available. At least one of the two following attributes are present : name : name of the shop guide : name of the guide The following attributes may be present : url : url of the shop country : country code town : town name
notes	X	X	X	STRING	all	notes for the dive (free field) readable only by owner	notes for the dive (free field)
public_notes	X		X	STRING	all	notes for the dive (free field)	notes for the dive (free field)
tanks	X	X	X	ARRAY of TANK object	private	Tanks used during the dive
gears	X				all	Gear used for the dive (Both user_gears and dive_gears)
user_gears	X	X	X	ARRAY of USER_GEAR object	all
dive_gears				ARRAY of DIVE_GEAR object	all
date	X		X	DATE	all	Date of the dive	YYYY-MM-DD
time	X		X	TIME	all	Time of the dive	HH:MM 24-hr, "local" timezone to the spot
dan_data	X	X	X	DAN Object	private	DO NOT USE
dan_data_sent	X		X		private	DO NOT USE
storage_used					private	DO NOT USE
profile_ref	X	X	X	STRING	private	Profile reference for UDCF uploads
pictures	X	X			mobile
number	X	X	X	INTEGER	all	Number of the dive in the logbook
send_to_dan		X				DO NOT USE
raw_profile	X	X	X	ARRAY of PROFILE_SAMPLE objects	public_with_profile	Dive profile data
featured_picture	X		X		mobile
featured_gears	X				mobile
other_gears					mobile

SAFETYSTOP

Each safety stop is stored as an array of the depth and the duration.

Position in Array	Type / Format	Mandatory/Optional	Description
0	INTEGER	MANDATORY	depth in meters
1	INTEGER	MANDATORY	time in minutes

example : [5,3] => 5 meters, 3 minutes stop

PROFILE_SAMPLE

Parameter	Can be nil	Type/Format	Comments
seconds	NO	INTEGER	time of the sample since the beginning of the dive
depth	YES	FLOAT	Unit: meters
current_water_temperature	YES	FLOAT	Unit: celsius degrees
main_cylinder_pressure	YES	FLOAT	Unit: bar
heart_beats	YES	FLOAT	Unit: beat per minutes
deco_violation	NO	BOOLEAN	defaults to false when absent, indicates when the diver has not respected his decompression procedure
deco_start	NO	BOOLEAN	defaults to false when absent,indicates when the dive started to have decompression stop (on top of the 3min for safety)
ascent_violation	NO	BOOLEAN	defaults to false when absent,indicates when the diver went up too fast
bookmark	NO	BOOLEAN	defaults to false when absent,indicates then the diver has logged a bookmark during the dive
surface_event	NO	BOOLEAN	defaults to false when absent,indicates when the diver has reached the surface

BUDDY

Parameter	Can be nil	Type/Format	Comments
name		STRING	Name of your buddy - free text
db_id	X	INTEGER	id of the buddy on diveboard
fb_id	X	INTEGER	facebook id of the buddy
email	X	STRING	email of your buddy
picturl	X	STRING	url to a picture of your buddy

DIVE_GEAR

Parameter	R	W	Can be nil	Type/Format	Present in flavours	Comments for read	Comments for write
id	X	X	X	INTEGER	all	the dive_gear object id	the dive_gear object id
category	X	X	X	STRING	all	in 'BCD','Boots','Computer','Compass','Camera','Cylinder','Dive skin','Dry suit','Fins','Gloves','Hood','Knife','Light','Lift bag','Mask','Other','Rebreather','Regulator','Scooter','Wet suit'	in 'BCD','Boots','Computer','Compass','Camera','Cylinder','Dive skin','Dry suit','Fins','Gloves','Hood','Knife','Light','Lift bag','Mask','Other','Rebreather','Regulator','Scooter','Wet suit'
manufacturer	X	X	X	STRING	all	Manufacturer’s name	Manufacturer’s name
model	X	X	X	STRING	all	Model’s name	Model’s name
featured	X	X	X	BOOL	all	true if the gear is featured in the dive	true if the gear is featured in the dive

USER_GEAR

Parameter	R	W	Can be nil	Type/Format	Present in flavours	Comments for read	Comments for write
id	X	X	X	INTEGER	all	the dive_gear object id	the dive_gear object id
category	X	X	X	STRING	all	in 'BCD','Boots','Computer','Compass','Camera','Cylinder','Dive skin','Dry suit','Fins','Gloves','Hood','Knife','Light','Lift bag','Mask','Other','Rebreather','Regulator','Scooter','Wet suit'	in 'BCD','Boots','Computer','Compass','Camera','Cylinder','Dive skin','Dry suit','Fins','Gloves','Hood','Knife','Light','Lift bag','Mask','Other','Rebreather','Regulator','Scooter','Wet suit'
manufacturer	X	X	X	STRING	all	Manufacturer’s name	Manufacturer’s name
model	X	X	X	STRING	all	Model’s name	Model’s name
featured	X	X	X	BOOL	all	true if the gear is featured in the dive	true if the gear is featured in the dive
acquisition	X	X	X	DATE	private	YYYY-MM-DD of acquisition	YYYY-MM-DD of acquisition
auto_feature	X	X	X	STRING	private	defines in which section the gear will go : select in 'never','featured','other'	defines in which section the gear will go : select in 'never','featured','other'
last_revision	X	X	X	DATE	private	YYYY-MM-DD of last revision	YYYY-MM-DD of last revision
reference	X	X	X	STRING	private	free field with reference number	free field with reference number

SPECIES

Parameter	Can be nil	Type/Format	Comments
id		STRING	Id of the species either "s-12435413" (scientific name) or "c-214324" (common name)
name	X	STRING	Preferred common name of the species
sname		STRING	Scientific name of the species
link	X	STRING	Link to species information page ( EOL.org )
thumbnail_href	X	STRING	url to a thumbnail of the fish picture
picture	X	STRING	url to a picture of the species

SHOP

Parameter	R	W	Can be nil	Type/Format	Present in flavours	Comments for read	Comments for write
id	X	X	X	INTEGER	all	the id of the dive shop to update if absent, a new dive will be created	the id of the dive shop to update if absent, a new dive will be created
name	X	X	X	STRING	all	the name of the dive shop	the name of the dive shop
lat	X	X	X	FLOAT	all	Latitude of the dive shop	Latitude of the dive shop
lng	X	X	X	FLOAT	all	Longitude of the dive shop	Longitude of the dive shop
address	X	X	X	STRING	all	the dive shop address	the dive shop address
email	X	X	X	STRING	all	contact email for the dive shop	contact email for the dive shop
web	X	X	X	STRING	all	url of the dive shop (including the leading http://)	url of the dive shop (including the leading http://)
phone	X	X	X	STRING	all	dive shop’s phone	dive shop’s phone
logo_url	X	X	X	INTEGER	all	url to the logo of the dive shop (including the leading http://)	url to the logo of the dive shop (including the leading http://)
dive_ids	X			ARRAY of (DIVE object).id	search_light	Array of ids of dives done in that spot	Array of ids of dives done in that spot
dive_count	X			INTEGER	search_light	Number of dives	Number of dives done in this spot

Spot

Parameter	R	W	Can be nil	Type/Format	Present in flavours	Comments for read	Comments for write
id	X	X	X	INTEGER	all	the id of the spot to update if absent, a new dive will be created	the id of the spot to update if absent, a new dive will be created
shaken_id	X			STRING	all
name	X	X		STRING	all	the name of the spot	the name of the spot
lat	X	X		FLOAT	all	Latitude of the dive shop	Latitude of the dive shop
lng	X	X		FLOAT	all	Longitude of the dive shop	Longitude of the dive shop
zoom	X	X		INTEGER	all	preferred zoom level for a nice render in a map (7-> 12)	preferred zoom level for a nice render in a map (7-> 12)
location		X		OBJECT	all	Where the spot is located
location_id	X			INTEGER	all		Where the spot is located
region		X	X	OBJECT	all	Body of water where the spot is located
region_id	X		X	INTEGER			Body of water where the spot is located
country_id	X	X		INTEGER	all	Country where the spot is located	Country where the spot is located
private_user_id	X	X	X	INTEGER	all	user id of the owner of the spot - is set spot is "private" i.e. not moderated	user id of the owner of the spot - is set spot is "private" i.e. not moderated
country_code	X	X		STRING	all		ISO Country code (2 letters) E.g. FR for France, GB for United Kingdom, MT for Malta
country_name	X			STRING	all	Full country name
country_flag_big	X			URL	all	URL to the big flag image
country_flag_small	X			URL	all	URL to the small flag image

LOCATION

A location is the area where a spot is located, mainly a big city, or a zone i.e. Sidney, NSW or San-Franciso...

Parameter	R	W	Can be nil	Type/Format	Present in flavours	Comments for read	Comments for write
id	X		X	INTEGER	all	the id of the location to update if absent, a new dive will be created	location can NOT be updated
name	X	X		STRING	all	the name of the location	the name of the location
country_id	X	X		INTEGER	all	country_id where location is	country_id where location is

REGION

A location is the body of water where a spot is located, Atlantic Ocean, Mediterranean Sea, Pacific Ocean...

Parameter	R	W	Can be nil	Type/Format	Present in flavours	Comments for read	Comments for write
id	X		X	INTEGER	all	the id of the location to update if absent, a new dive will be created	location can NOT be updated
name	X	X		STRING	all	the name of the location	the name of the location

TANKS

Parameter	R	W	Can be nil	Type/Format	Present in flavours	Comments for read	Comments for write
id	X	X	X	INTEGER	all	Tank id	Tank id
material	X	X	X	STRING	all	string in 'aluminium','steel'	string in 'aluminium','steel'
gas	X	X	X	STRING	all	string in 'air','EANx32','EANx36','EANx40','custom'	string in 'air','EANx32','EANx36','EANx40','custom'
volume	X	X	X	FLOAT	all	Volume of the tank in L	Volume of the tank in L
multitank	X	X	X	INTEGER	all	number of such tanks (1 or 2 for dual tanks)	number of such tanks (1 or 2 for dual tanks)
o2	X	X	X	INTEGER	all	percentage of o2 in gaz 0-100 only used if gas=’custom’	percentage of o2 in gaz 0-100 only used if gas=’custom’
n2	X	X	X	INTEGER	all	percentage of n2 in gaz 0-100 only used if gas=’custom’	percentage of n2 in gaz 0-100 only used if gas=’custom’
he	X	X	X	INTEGER	all	percentage of he in gaz 0-100 only used if gas=’custom’	percentage of he in gaz 0-100 only used if gas=’custom’
time_start	X	X	X	INTEGER	all	time in minutes from the start of the dive when diver switched to this tank	time in minutes from the start of the dive when diver switched to this tank
p_start	X	X	X	FLOAT	all	Initial pressure in bottle in bar	Initial pressure in bottle in bar
p_end	X	X	X	FLOAT	all	Final pressure in bottle in bar	Final pressure in bottle in bar

UNITS

The attribute "Units" is deprecated. To get or set the preferred units of a user, use the preferred_units attribute.

Name	Type / Format	Mandatory/Optional	Null?	Description
distance	STRING "m" or “ft”	M	N
weight	STRING “kg” or “lbs”	M	Y
temperature	STRING “C” or “F”	M	Y
pressure	“bar” or “psi”	M	Y

Object ERROR

Name	Type / Format	Mandatory/Optional	Null?	Description
error	STRING	M	N	technical error message
object	OBJECT	M	Y	the part of the input parameter that is responsible for the error (for debugging purposes)
error_code		M	N	error code (will be implemented in future version)