API documentation

Mobypicture has a REST based API, with the most used functions on the website. The API is in active development, if you have any comment, feedback or feature-request. Please contact us.

API-calls are HTTP-requests made to http://api.mobypicture.com or to https://api.mobypicture.com (SSL).

In the documentation below you can find out more about the usage of the Mobypicture API. To use the API you have to get a developer key. This also allows you to promote your mobypicture enabled app on the mobypicture website.


get a mobypicture developer key


We have the following types of API calls:
  • postMedia For distributing media through Mobypicture
  • postMediaUrl For distributing media and getting the Mobypicture tinyurl of the post
  • getThumb For embedding thumbnails in your HTML
  • getThumbUrl For fetching the thumbnail URL of a Mobypicture tinyurl
  • getMediaInfo For requesting information about a posting
  • checkCredentials For checking if specified credentials are valid.
  • postComment Adds a comment to a posting.
  • getComments Retrieves all comments for a posting.
  • searchPosts Searches for postings.
  • createUser Creates a Mobypicture user
  • getUser Get a Mobypicture user's details
  • getFriends Get the Mobypicture user's friends
  • addFriend Add a friend to a Mobypicture user
  • oEmbed oEmbed is a format for allowing an embedded representation of a URL on third party sites.


In order to use a specific function, you need to supply the following field:
Field name Description Example
action Specifies the API function to be used postMediaUrl


Furthermore, there is a list of error codes available.
All calls to our API must include your developer key.

response formatting

You can specify in which format you wish to receive the response.
Currently we support the following formats:
Field name Description Example
format Plaintext plain
format XML xml
format format json

postMedia
Distributing media via Mobypicture is done by doing a HTTP-POST call to our servers.
Please make sure you are using multipart/form-data as your encoding type.

There is no need to specify which kind of file you are uploading (photo/audio/video), just make sure
the file gets to us in one piece and we'll sort things out.

Currently we support the following filetypes:

Photo
  • jpeg
  • png
  • bmp
  • gif
Video
  • flv
  • mpeg
  • mkv *
  • wmv
  • mov
  • 3gp
  • mp4
  • avi *
Audio
  • mp3
  • wma
  • aac
  • aif
  • au
  • flac
  • ra
  • wav
  • ogg
  • 3gp
* Please note:
Due to different ways of encoding video files we may not be able to process some files, even when they appear in this list

The following fields are required for this call:
Field name Max. length Description Example
i 16 MB Image (binary jpeg data)
u 32 User login somemobyuser
p 32 User password somepassword
k 32 Developer Key aaaaaaaa


The following fields are optional:
Field name Max. length Description Example
t 512 Title My new car!
d 10000 Description Remember about my new car? Well here it is!
tags 100 Tags red car,ferrari
latlong 32 Location (lat/long) 52.364882,4.902349
ht 32 Hashtag(s) #020
s 64 Service(s) twitter,flickr,tumblr
or: none,+twitter
or: all,-twitter
taken_on 64 Taken on (ISO 8601 date) 2009-10-27T15:19:21+01:00
format 64 format xml


Note: If you only supply a description (and no title), the description will automatically be used as title.

You can test posting to Mobypicture by using our very basic POST-testing tool

An example of this function by using cURL:


<?php
    
function postMobypicture($username, $pin, $filePath, $postTitle, $postDescription)
{
    $url = 'http://api.mobypicture.com';
    $apiKey = 'YOU-APIKEY-HERE';

    $postVars = array();
    $postVars['k'] = $apiKey;            // Your API key
    $postVars['u'] = $username;            // Username 
    $postVars['p'] = $pin;                // Password 
    $postVars['i'] = '@'.$filePath;        // Path of the file to send
    $postVars['t'] = $postTitle;        // Title of the post
    $postVars['d'] = $postDescription;    // Description of the post
    $postVars['format'] = 'xml';        // Response format, can be 'xml', 'json' or 'plain';

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $postVars);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
    curl_setopt($ch, CURLOPT_HEADER, 0); 
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); 
    $returnData = curl_exec($ch);
    curl_close($ch);

    /**
     * Do something with the returned data
     */
    var_dump ($returnData);
}
    
postMobypicture('bram', '1234', '/mnt/fileserver/media/IMAGE_058.jpg', 'Nala the cat', 'Meow!');

?>

postMediaUrl
This function is accepts exactly the same parameters as postMedia, but instead of returning only whether the post was successful or not, you also get the tinyurl of the post on Mobypicture.

getThumb
This function allows developers to get the location of the photo associated with a Mobypicture URL by doing a HTTP-GET request (which are posted on sites like Twitter).

The following fields are accepted for this call:
Field name Max. length Description Example
t 32 Tiny URL http://moby.to/lycbhe
s 32 Size (thumbnail, small, square or medium) small
k 32 Developer Key aaaaaaaa
format 64 format plain



The previous examples would result in the following GET-request:

http://api.mobypicture.com?t=http://moby.to/lycbhe&s=small&k=aaaaaaa&format=plain


To test this call, you can use our our very basic GET-testing tool

getThumbUrl
This function is accepts exactly the same parameters as getThumb, but instead of redirecting you to the location of the thumbnail, it will be returned as plaintext HTTP-response.

An example of this function by using cURL:

function getMobyThumb($tinyUrlCode)
{
   $mobyDeveloperKey = '[MOBYPICTURE_API_KEY_HERE]';
   $mobyUrl = 'http://api.mobypicture.com/?';
   $mobyUrl .= 'action=getThumbUrl&';
   $mobyUrl .= 't='.urlencode($tinyUrlCode).'&';
   $mobyUrl .= 's=small&k='.urlencode($mobyDeveloperKey).'&';
   $mobyUrl .= 'format=plain';

   $curlObj = curl_init();
   curl_setopt($curlObj, CURLOPT_URL, $mobyUrl);
   curl_setopt($curlObj, CURLOPT_VERBOSE, 0);
   curl_setopt($curlObj, CURLOPT_RETURNTRANSFER, 1);
   curl_setopt($curlObj, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
   $mobyImageUrl = curl_exec($curlObj);
   curl_close($curlObj);

   return $mobyImageUrl;
}

getMediaInfo
Returns information about a posting. Fields that are not available will be returned empty

The following fields are accepted for this call:
Field name Description Example
t Tiny URL code lycbhe
k Developer Key aaaaaaaa
format format json


Returns:

<?xml version="1.0"?>
<mobypicture>
    <result code="0"></result>
    <user>
       <username>mathys</username>
       <firstname>Mathys</firstname>
       <lastname>van Abbe</lastname>
       <url_avatar>http://www.mobypicture.com/images/avatar/95af43f04454d5c61cb83d10288aa937_60px.jpg</url_avatar>
    </user>
    <post>
       <title>Prinses Amelie</title>
       <description>Verstuurd vanaf mijn iPhone</description>
       <location_latlong></location_latlong>
       <created_on>2008-11-25 20:16:15</created_on>
       <created_on_epoch>1227640575</created_on_epoch>
       <views>7</views>
       <media>
          <url_thumbnail>http://img.mobypicture.com/ea0ea9b57c00a391ac7a905fc0502426_thumbnail.jpg</url_thumbnail>
          <url_square>http://img.mobypicture.com/ea0ea9b57c00a391ac7a905fc0502426_square.jpg</url_square>
          <type>photo</type>
          <original_width>800</original_width>
          <original_height>600</original_height>
       </media>
       <device>
          <manufacturer></manufacturer>
          <model></model>
       </device>
       <link>http://www.mobypicture.com/mathys/view/71807</link>
       <link_tiny>http://moby.to/lycbhe</link_tiny>
    </post>
</mobypicture>

checkCredentials
Checks whether the user is a valid Mobypicture user. Unless specified otherwise, it will -in case of a non-existing user on Mobypicture- also check whether the supplied credentials are belonging to a Twitter-user. If so, it will automatically create a Mobypicture for it.

The following fields are accepted:
Field name Max. length Description Example
u 32 Username somemobyuser
p 32 Password somepassword
k 32 Developer Key aaaaaaaa
format 64 format plain

postComment
Adds a comment to a posting. Requires username + pin or name + email. The following fields are accepted:
Field name Value(s) Example Description
u string somemobyuser Username (can be a Twitter username)
p string somepin PIN or password
name string John Smith Name (not used in case an username has been supplied)
email string john@smith.com
 Email (not used in case an username has been supplied)
tinyurl_code string bvs2wx
 The tinyurl-code associated with a posting
message string Nice boat!
 Comment
tweet 0, 1 1 Tweets this comment on Twitter if possible with the supplied credentials

getComments
Retrieves all comments for a giving posting.
In addition to the standard fields (k, format, action), one of the following fields should be added:
Field name Value(s) Example Description
tinyurl_code string bvs2wx
 The tinyurl-code associated with a posting
post_id string 1234567
 The ID of the posting

searchPosts
To search in postings using the API you need to do a GET-request with the following variables:
Field name Example value(s) Description
k [DEVELOPERKEY]
 Your developer key
action 'searchPosts'
 The action that should be performed. 'searchPosts' to search.
format 'xml'
 Specifies in which format the response should be returned
searchItemsPerPage '10'
 Amount of posts to show on each page
searchPage '1'
 The current page
searchTerms 'mobypicture -http'
 Specifies for which words to search.
searchIn 'both'
 Specifies in what fields to search ('title', 'description' or 'both')
searchUsername 'mathys'
 Only return postings from the specified username
searchMediaPhoto '0' or '1'
 Include photo posts in the search (default is '1' - on)
searchMediaVideo '0' or '1'
 Include video posts in the search (default is '1' - on)
searchMediaAudio '0' or '1'
 Include audio posts in the search (default is '1' - on)
searchGeoCountry 'NL'
 Only return postings from the specified country (ISO3166 code2)
searchGeoCity 'Amsterdam'
 Only return postings from the specified country
searchTags 'car,ferrari'
 Look for one or more tags (comma seperated)
searchSortBy 'relevant', 'recent' or 'views'
 Sort the results based on this field.
searchOrder 'asc', 'desc'
 Specifies in which direction sorting should be done.

examples

Returns all postings from Holland, with the word 'windmill' in the title or description, but without the word'dutch':

http://api.mobypicture.com/?action=searchPosts&k=DEVELOPERKEY&format=xml&searchTerms=windmill%20-dutch&searchGeoCountry=NL&searchItemsPerPage=50&searchPage=1

createUser
To create a Mobypicture user you need to do a GET or POST-request with the following variables:
Field name Example value(s) Description
k [DEVELOPERKEY]
 Your developer key
action 'createUser'
 The action that should be performed. 'createUser' to create a new user.
format 'xml'
 Specifies in which format the response should be returned
username 'mobyusername'
 Specifies the desired username
pin '0123'
 Specifies the desired PIN
email 'user@domain.com'
 Specifies the emailaddress of the registrant
firstname 'john'
 Specifies the first name of the registrant (required)
lastname 'smith'
 Specifies the last name of the registrant
keepposted 'yes' or 'no'
 Specifies whether the registrant wants to receive additional announcements.
agreeterms 'yes' or 'no'
 Specifies whether the registrant agrees to the mobypicture terms of service ('yes' is required).

getUser
To get the user details of a Mobypicture user you need to do a GET or POST-request with the following variables:
Field name Example value(s) Description
k [DEVELOPERKEY]
 Your developer key
action 'getUser'
 The action that should be performed. 'getUser' get the user details of a Mobypicture user.
format 'xml'
 Specifies in which format the response should be returned
u 'mobyusername'
 Specifies the username

getFriends
To get the friends of a Mobypicture user you need to do a GET or POST-request with the following variables:
Field name Example value(s) Description
k [DEVELOPERKEY]
 Your developer key
action 'getFriends'
 The action that should be performed. 'getFriends' get the friends of a Mobypicture user.
format 'xml'
 Specifies in which format the response should be returned
u 'mobyusername'
 Specifies the username

addFriend
To add a friend to a Mobypicture user you need to do a GET or POST-request with the following variables:
Field name Example value(s) Description
k [DEVELOPERKEY]
 Your developer key
action 'addFriend'
 The action that should be performed. 'addFriend' to add a friend of a Mobypicture user.
format 'xml'
 Specifies in which format the response should be returned
u 'mobyusername'
 Specifies the username

oEmbed
oEmbed is a format for allowing an embedded representation of a URL on third party sites. The simple API allows a website to display embedded content (such as photos or videos) when a user posts a link to that resource, without having to parse the resource directly.
Field name Example value(s) Description
url http://www.mobypicture.com/user/marjolijn/view/90053
 The URL to retrieve embedding information for.
format (optional) xml
 The required response format. JSON and XML re supported, defaults to XML
maxwidth (optional) 1900
 The maximum width of the embedded resource.
maxheight (optional) 1080
 The maximum height of the embedded resource.

More documentation on oEmbed can be found on http://oembed.com

URL scheme: http://www.mobypicture.com/user/*/view/*
API endpoint: http://api.mobypicture.com/oEmbed
Supports discovery via tags
Example: http:/api.mobypicture.com/oEmbed?url=http://www.mobypicture.com/user/marjolijn/view/90053&format=xml

URL scheme: http://moby.to/*
API endpoint: http://api.mobypicture.com/oEmbed
Example: http:/api.mobypicture.com/oEmbed?url=http://moby.to/1234&format=xml

Errors

The following HTTP status codes are defined as part of the oEmbed specification:

HTTP Status Code Description
404 Not Found The provider has no response for the requested url parameter. This allows providers to be broad in their URL scheme, and then determine at call time if they have a representation to return.
501 Not Implemented The provider cannot return a response in the requested format. This should be sent when (for example) the request includes format=xml and the provider doesn't support XML responses. However, Mobypicture supports both JSON and XML.
401 Unauthorized The specified URL contains a private (non-public) resource. The consumer should provide a link directly to the resource instead of any embedding any extra information, and rely on the provider to provide access control.

Error Codes
Here is a list of possible returned error codes:
(More explanation will follow later on)

0
- Success

99
- Something went very, very wrong. (Does not happen alot)

100 API is currently unavailable
- API has been disabled for maintenence, retry later

101 Invalid action
- Current accepted actions are: postMedia, postMediaUrl, getThumb, getThumbUrl, checkCredentials

102 Invalid developer key
- Are you sure you're sending your developer key along? It needs to be in the 'k' field.

103 Invalid username or password
- We can not process this post because the user does not exist, or the password is incorrect.

104 Uploading files must be done by HTTP-POST
- You tried to upload a file while doing a GET, HEAD, PUT or OPTION request.. not gonna happen. Try HTTP-POST.

105 Upload error <PHP file-upload error code>
- Please check the following website for an explanation: PHP Uploading Files: Error Messages Explained

106 Could not open uploaded file
- Crap, you might be doing something stupid, or we are failing miserably... Are you sure you're using multipart/form-data as enctype? Anyways, this is not working out. Please tell us if experience this error.

107 File was not a valid image
- We currently support: JPEG, PNG, BMP and GIF. Perhaps other filetypes also work, but we are not promising you that.

108 File could not be opened as a valid image
See 107.

200 Could not create post
- Due to technical difficulties we were not able to process your posting. Our deepest apologies.

301 Could not find valid tinyurl by given code
- The specified tinyurl seems to not-exists in our system. Try just opening the link in your browser. Still doesn't work? Then it doesn't exist.

302 Could not find associated post
- We know this tinyurl, but it's not mapped to an existing posting in our system? This is a fatal error.

303 Could not find tinyurl-code in url
- You are using the good old 'getThumb' method, which needs a complete (or at least /?tinycode) URL sent along with it.
Use 'getThumbUrl' if you just want to send the tinycode.

401 Invalid username or password
- The given username/password combination does not belong to a Mobypicture or Twitter user.

800 This format is unsupported for this function

888 Not yet implemented
- This feature is currently being implemented, stay tuned.