API Documentation
Consumer registration
For accessing the site API, you'll first need to register your consumer and obtain a consumer key and a consumer secret.
Available serialization formats
All the API methods can return data serialized into xml, json and yaml.
API Authentication
-
HTTP Basic Authentication
HTTP Basic authentication is available using the http://bynotes.com/api/1.0/rest/basic/ base URL. When authenticating using this method, you must suply the username and the API password as the HTTP credentials. Currently, this authentication method does not require a consumer key, but this may change in the future.
-
OAuth Authentication
OAuth authentication is available using the http://bynotes.com/api/1.0/rest/oauth/ base URL. The following endpoints deal with tokens:
- Request token: http://bynotes.com/api/1.0/oauth/request_token
- Authorize token: http://bynotes.com/api/1.0/oauth/authorize
- Access token: http://bynotes.com/api/1.0/oauth/access_token
Default token expiration is 1 hour, however you can request access for longer time intervals using the oauth_token_duration (in seconds) parameter when obtaining a new request token.
API Endpoints
User information
-
user/me.{ format } Requires login
allowed methods: GETReturns publicly available information for the logged-in username.
-
user/user.{ format }
allowed methods: GETReturns publicly available information for the given username.
Required parameters:
user (String): The username you want to retrieve information for
Positions
-
position/position.{ format } Requires login
allowed methods: GETReturns the last position for the logged in user. If a username is provided, it returns the last position for that user.
Optional parameters:
user (String): Username for the user you want to retrieve the position for.
Fetching notes
-
notes/note.{ format }
allowed methods: GETReturns the note with the given note id.
Required parameters:
id (Integer): The id of the note you want to fetch.
-
notes/received.{ format } Requires login
allowed methods: GETReturns the received notes for the logged in user.
Optional parameters:
include_mine (Boolean): Wheter to include notes posted by the logged-in user
Default: False
since_id (Integer): Return only notes with id greater than since_id.
offset (Integer): Skip the first offset notes.
Default: 0
Minimum value: 0
limit (Integer): The maximum number of notes returned.
Default: 30
Maximum value: 50
Minimum value: 1
-
notes/timeline.{ format }
allowed methods: GETReturns latest public notes. If a geoname is provided, only notes posted from it and its children will be returned.
Optional parameters:
since_id (Integer): Return only notes with id greater than since_id.
offset (Integer): Skip the first offset notes.
Default: 0
Minimum value: 0
limit (Integer): The maximum number of notes returned.
Default: 30
Maximum value: 50
Minimum value: 1
exclude_mine (Boolean): Wheter to exclude notes posted by the logged-in user.
Default: False
geoname (Integer): Geoname identifier for the area you want to restrict notes to.
-
notes/user.{ format }
allowed methods: GETReturns notes from user visible for the current logged-in user (if any).
Required parameters:
user (String): Username you want to retrieve the notes for.
Optional parameters:
since_id (Integer): Return only notes with id greater than since_id.
offset (Integer): Skip the first offset notes.
Default: 0
Minimum value: 0
limit (Integer): The maximum number of notes returned.
Default: 30
Maximum value: 50
Minimum value: 1
Friends
-
friends/add.{ format } Requires login
allowed methods: GET POSTAdds the specified user to the logged in user's friend list
Optional parameters:
user (String): Username for the user you want to add as friend.
-
friends/friends.{ format } Requires login
allowed methods: GETReturns the friends for the current logged in user.
-
friends/positions.{ format } Requires login
allowed methods: GETReturns the friends for the current logged in user with their latest positions.
-
friends/remove.{ format } Requires login
allowed methods: GET POSTRemoves the specified user from the logged in user's friend list
Optional parameters:
user (String): Username for the user you want to remove from your friends list.
Posting notes
-
post/event.{ format } Requires login
allowed methods: GET POSTPost a new event note
Required parameters:
address (UTF-8 String): Your current position specified as full a address or as a lat,lng pair in decimal degrees.
datetime (String): The local date and time when the event is going to happen in %Y-%m-%d %H:%M:%S format. Seconds can be omitted.
Maximum length: 50
place_name (UTF-8 String): Place name for the event (this is only for display, this parameter is not for the full address).
Maximum length: 50
what (UTF-8 String): What the event is about.
Maximum length: 50
Optional parameters:
message (UTF-8 String): The message to be included in the note.
Default:
Maximum length: 1000
destination (String): The destination type.
Default: P
Valid choices: P (Public), F (All friends), S (Selected friends)
receivers (String): When using the S destination type, this parameter should contain the user names you are sending this note to as a comma-separated list. Note you can only send notes to friends.
Default:
inreplyto (Integer): Make the current note a reply to note #inreplyto.
attendance (String): When replying to an event note, this parameter is used for specifying the user attendance.
Default: U
Valid choices: U (I still don't know), Y (Yes), N (No), M (Maybe), S (Sure!), B (No, I'm busy), I (No, I'm not interested)
-
post/file.{ format } Requires login
allowed methods: GET POSTPost a new file note
Required parameters:
file (File): The file you want to post (standard post file upload)
Maximum file size: 50M
Optional parameters:
message (UTF-8 String): The message to be included in the note.
Default:
Maximum length: 1000
address (UTF-8 String): Your current position specified as full a address or as a lat,lng pair in decimal degrees.
destination (String): The destination type.
Default: P
Valid choices: P (Public), F (All friends), S (Selected friends)
receivers (String): When using the S destination type, this parameter should contain the user names you are sending this note to as a comma-separated list. Note you can only send notes to friends.
Default:
inreplyto (Integer): Make the current note a reply to note #inreplyto.
attendance (String): When replying to an event note, this parameter is used for specifying the user attendance.
Default: U
Valid choices: U (I still don't know), Y (Yes), N (No), M (Maybe), S (Sure!), B (No, I'm busy), I (No, I'm not interested)
-
post/link.{ format } Requires login
allowed methods: GET POSTPost a new link note
Required parameters:
link (String): The full URL of the link you want to include in the note.
Maximum length: 512
Optional parameters:
message (UTF-8 String): The message to be included in the note.
Default:
Maximum length: 1000
address (UTF-8 String): Your current position specified as full a address or as a lat,lng pair in decimal degrees.
destination (String): The destination type.
Default: P
Valid choices: P (Public), F (All friends), S (Selected friends)
receivers (String): When using the S destination type, this parameter should contain the user names you are sending this note to as a comma-separated list. Note you can only send notes to friends.
Default:
inreplyto (Integer): Make the current note a reply to note #inreplyto.
attendance (String): When replying to an event note, this parameter is used for specifying the user attendance.
Default: U
Valid choices: U (I still don't know), Y (Yes), N (No), M (Maybe), S (Sure!), B (No, I'm busy), I (No, I'm not interested)
-
post/message.{ format } Requires login
allowed methods: GET POSTPost a new message note
Required parameters:
message (UTF-8 String): The message to be included in the note.
Maximum length: 1000
Optional parameters:
address (UTF-8 String): Your current position specified as full a address or as a lat,lng pair in decimal degrees.
destination (String): The destination type.
Default: P
Valid choices: P (Public), F (All friends), S (Selected friends)
receivers (String): When using the S destination type, this parameter should contain the user names you are sending this note to as a comma-separated list. Note you can only send notes to friends.
Default:
inreplyto (Integer): Make the current note a reply to note #inreplyto.
attendance (String): When replying to an event note, this parameter is used for specifying the user attendance.
Default: U
Valid choices: U (I still don't know), Y (Yes), N (No), M (Maybe), S (Sure!), B (No, I'm busy), I (No, I'm not interested)
-
post/position.{ format } Requires login
allowed methods: GET POSTPost a new position note
Required parameters:
address (UTF-8 String): Your current position specified as full a address or as a lat,lng pair in decimal degrees.
Optional parameters:
destination (String): The destination type.
Default: P
Valid choices: P (Public), F (All friends), S (Selected friends)
receivers (String): When using the S destination type, this parameter should contain the user names you are sending this note to as a comma-separated list. Note you can only send notes to friends.
Default:
inreplyto (Integer): Make the current note a reply to note #inreplyto.
attendance (String): When replying to an event note, this parameter is used for specifying the user attendance.
Default: U
Valid choices: U (I still don't know), Y (Yes), N (No), M (Maybe), S (Sure!), B (No, I'm busy), I (No, I'm not interested)
Geographic functions
-
geo/admin.{ format }
allowed methods: GETReturns information for the given administrative division type and id. Keep in mind that administrative divisions identificators are not guaranteed to be permanent, as it happens when geoname identifiers.
Required parameters:
id (Integer): The administrative division id.
type (Integer): Admin division type, ranging from 1 to 4.
Maximum value: 4
Minimum value: 1
-
geo/geocode.{ format }
allowed methods: GET POSTReturns the result for geocoding the given address. Any returned status value other than 200 will mean the geocoding failed. The "request_id" field can be reused for other functions.
Required parameters:
address (String): The address you want to geocode.
-
geo/geoname.{ format }
allowed methods: GETReturns information about a given geoname, like class and code, coordinates, ...
Required parameters:
id (Integer): The geoname id you want to retrieve information for.
Optional parameters:
parent (Boolean): Wheter to include information for the parent location.
Default: False
-
geo/hierarchy.{ format }
allowed methods: GETReturns the hierarchy for the given geoname id, starting from itself.
Required parameters:
id (Integer): The geoname id you want to retrieve information for.
Documentation for this API has been automatically generated using WAPI