The Riya API provides a set of methods that you can use to integrate Riya's image searching technology into your own application. The API uses the standard HTTP GET and HTTP POST requests in the Representational State Transfer (REST) style.
Please note that the riya.photos.upload.UploadPhoto method requires the POST method. All other methods in the Riya API require the GET method.
Before you can use the Riya API, you'll need an API Key. To use
the methods in the API, you'll need to pass two required parameters, method and api_key, in addtion to any parameters that the
specific method requires. Most methods require authentication. You must pass the user_name and auth_token parameters to any method that requires authentication. The method parameter must contain the name of the method you're calling. The api_key parameter must contain your API key.
Riya stores the images you upload in two sizes. The thumbnail size is used to display a list of images. Thumbnails are 160 by 120 pixels in size. The screen resolution image is used to display the image when the user selects it and is 800 by 600 pixels in size.
All the PHP code examples in this document require the riyaapi.class.php.html file, which you can download here.
To use a Riya API method, send an HTTP GET or HTTP POST request to the API endpoint, http://www.riya.com/rest.
Append the method's parameters to the URL, as in the following example.
The riya.auth.GetToken method requires the user_name and password parameters, in addition to
the mandatory parameters method and api_key. The complete URL that your web application passes in the HTTP GET request is:
The ? character after http://www.riya.com/rest indicates the beginning of your request. The parameter names are separated from the parameter values by the = character. Indicate the beginning of each parameter name-value pair after the first with the & character.
When the method you call returns successfully, the HTTP request returns an XML file with the results. You can parse this file and use the information in your application, typically to format the resulting HTML page or to pass to other Riya API methods. In the example above, the riya.auth.GetToken method returns an authentication token in the following format:
Most of the methods in the Riya API require an authentication token. The only method in the API that does not require a token
is the public search method riya.photos.search.SearchPublic. In general, it's a good idea to get an authentication token as the very first step in any Riya web application.
To get an authentication token, pass your user's username and password to riya.com with the riya.auth.GetToken method, as in
the following example.
After your application parses the token from the XML response, your user can perform any of the tasks that the API makes possible. We'll discuss these tasks in the following sections.
It's likely that the first thing you'll want to do is upload images to your account. Images must be in the JPEG file format, and the minimum resolution is 100 by 100 pixels. You can use the
Riya Uploader, or you can upload single images manually using riya.photos.upload.UploadPhoto. Note that, while all of the other methods in this API use the GET method, the riya.photos.upload.UploadPhoto method uses POST.
<?php
require_once 'riyaapi.class.php';
$r = new RiyaAPI();
$r->setApiKey(your API key);
$r->setUsername(username);
$r->setAuthToken($r->getAuthToken(password));
$response = $r->callMethod('riya.photos.upload.UploadPhoto', array(
'photo' => './test.gif', // Replace this with the photo path
'access' => 'private-access', // public-access/private-access
));
if ( $response !== false ) {
// Parse photo data from XML
$photo = RiyaApi::parseAttributes($response->photo);
// Output success message with ID
echo 'Photo uploaded successfully. ID: ' . $photo['id'];
} else {
echo 'Error Code: ' . $r->getErrorCode() . ' ';
echo 'Error Message: ' . $r->getErrorMessage() . ' ';
}
?>
The riya.photos.upload.UploadPhoto method requires the access, user_name, and api_key parameters. The access parameter can take on two values, private-access and public-access. When this method completes successfully, it returns a unique ID string for the image.
<image_id="b74799e325de61ad"/>
After you've uploaded an image, you can mark it as Public or Private. A Private image is not visible on public searches. You can search through all of your own Private images. To mark an image as Private or Public, call the riya.photos.ChangePhotoPermission method. This method requires the image_id and access parameters. Any user can make any image Private, but only the image's owner can change a Private image to Public.
When you upload an image, riya.com automatically performs facial recognition on the image, drawing a rectangle around each face that it detects. If the face matches a face that you've already trained Riya to recognize, Riya automatically enters the name for the recognized face. You can enter names for any new faces that Riya hasn't recognized, or correct the names for faces that Riya may have identified incorrectly.
You can call the riya.photos.faces.IdentifyFace method to alter the name that Riya assigns to a face. This method requires the image_id, face_id, and full_name parameters. The image_id parameter uniquely identifies the image that contains the face you want to rename. The face_id parameter uniquely identifies the specific face in the image. The full_name parameter is the name you want to assign to that face.
<?php
require_once 'riyaapi.class.php';
$r = new RiyaAPI();
$r->setApiKey(your API key);
$r->setUsername(username);
$r->setAuthToken($r->getAuthToken(password));
$response = $r->callMethod('riya.photos.faces.IdentifyFace', array(
'image_id' => image ID,
'face_id' => face ID,
'full_name' => full name
));
if ( $response !== false ) {
// Dumps the object to screen
echo '<pre>';
print_r($response);
echo '</pre>';
} else {
echo 'Error Code: ' . $r->getErrorCode() . ' ';
echo 'Error Message: ' . $r->getErrorMessage() . ' ';
}
?>
If there's a face in an uploaded picture that Riya didn't detect as a face, you can use the riya.photos.faces.AddFace method to mark the area of the image where the face is. This method requires the image_id, x, y, w, and h parameters. The x and y parameters define the pixel coordinates of the top left corner of the rectangle. The w parameter specifies the width of the rectangle in pixels. The h parameter specifies the height of the rectangle in pixels.
<?php
require_once 'riyaapi.class.php';
$r = new RiyaAPI();
$r->setApiKey(your API key);
$r->setUsername(username);
$r->setAuthToken($r->getAuthToken(password));
$response = $r->callMethod('riya.photos.faces.AddFace', array(
'image_id' => image ID,
'x' => x-coordinate,
'y' => y-coordinate,
'w' => width,
'h' => height,
));
if ( $response !== false ) {
// Parse face data from XML
$face = RiyaApi::parseAttributes($response->face);
// Output success message with ID
echo 'Face added successfully. ID: ' . $face['id'];
} else {
echo 'Error Code: ' . $r->getErrorCode() . ' ';
echo 'Error Message: ' . $r->getErrorMessage() . ' ';
}
?>
In this method, both the X and Y coordinates and the height and width dimensions are relative to the top-left corner of the thumbnail (160x120) image. When this method completes successfully, it returns a unique ID for the face.
Riya may incorrectly identify an area in your image as a face. You can call the riya.photos.faces.RemoveFace method to remove these misidentified areas. This method requires the image_id and face_id parameters.
To get a list of all the faces that Riya can identify in a given image, call the riya.photos.faces.GetFaceList method. This method requires the image_id parameter.
In this method, both the X and Y coordinates and the height and width dimensions are relative to the top-left corner of the thumbnail (160x120) image. When this method completes successfully, it returns a list of the unique face IDs that are present in the image.
Overlays are rectangular areas in an image that you define. Riya automatically performs text recognition inside an overlay and adds any detected text to the overlay's label, in addition to the automatic text recognition that Riya performs when you upload an image. You can search for overlays by label just as you can search for faces by name. You can use overlays to call out areas of interest in your image that aren't faces, and define their labels in any way you want.
To create a new overlay in an image, call the riya.photos.overlays.AddOverlay method. This method requires the image_id, x, y, w, and h parameters. The x and y parameters define the pixel coordinates of the top left corner of the rectangle. The w parameter specifies the width of the rectangle in pixels. The h parameter specifies the height of the rectangle in pixels. In this method, both the X and Y coordinates and the height and width dimensions are relative to the top-left corner of the thumbnail (160x120) image.
To change the label for an overlay, call the riya.photos.overlays.EditOverlay method. This method requires the image_id, overlay_id, and tag parameters. The tag parameter contains the value that you want to assign to the overlay's label.
Comments and tags are text labels that anyone can append to an image on Riya.com. Comments and tags can only be deleted by the image's owner. You can search for a specific tag to find images, but you cannot search through comments.
To add a tag to an image, call the riya.photos.tags.AddTag method. This method requires the image_id and tag parameters. The tag parameter contains the value that you want to assign to the image.
<?php
require_once 'riyaapi.class.php';
$r = new RiyaAPI();
$r->setApiKey(your API key);
$r->setUsername(username);
$r->setAuthToken($r->getAuthToken(password));
$response = $r->callMethod('riya.photos.tags.AddTag', array(
'image_id' => image ID,
'tag' => tag contents,
));
if ( $response !== false ) {
// Parse tag data from XML
$tag = RiyaApi::parseAttributes($response->tag);
// Output success message with ID
echo 'Tag added successfully. ID: ' . $tag['id'];
} else {
echo 'Error Code: ' . $r->getErrorCode() . '<br />';
echo 'Error Message: ' . $r->getErrorMessage() . '<br />';
}
?>
To list all the tags on an image, call the riya.photos.tags.GetTagList method. This method requires the image_id parameter.
To add a comment to an image, call the riya.photos.comments.AddComment method. This method requires the image_id and comment parameters. The comment parameter has the value of the comment that you want to add to the image.
<?php
require_once 'riyaapi.class.php';
$r = new RiyaAPI();
$r->setApiKey(your API key);
$r->setUsername(username);
$r->setAuthToken($r->getAuthToken(password));
$response = $r->callMethod('riya.photos.comments.AddComment', array(
'image_id' => image ID,
'comment' => comment text,
));
if ( $response !== false ) {
// Parse comment data from XML
$comment = RiyaApi::parseAttributes($response->comment);
// Output success message with ID
echo 'Comment added successfully. ID: ' . $comment['id'];
} else {
echo 'Error Code: ' . $r->getErrorCode() . '<br />';
echo 'Error Message: ' . $r->getErrorMessage() . '<br />';
}
?>
This method returns an XML identifier for the comment.
Riya stores the names of any faces you've identified in your photoset in an address book. A Contact is an entry in your address book. The address book holds names and email addresses. You can retrieve the list of all your contacts with the riya.contacts.GetContactList method.
To get a list of all the faces in your photoset that are associated with a particular name, use the riya.contacts.GetFaceShots method. This method requires the full_name parameter. This method returns an XML list of the face thumbnails matching the name that you specify in the full_name parameter.
When you upload images to Riya with the Uploader, the Uploader automatically assigns your images to albums based on the pathnames where the image files are located. You can also specify an album for an image when you upload it by using the riya.photos.upload.UploadPhoto method. The riya.albums.GetAlbums method shows all the albums for a given user.
Each album is displayed with a link to a representative image for that album. The representative image is the first image in that image set. This method also returns the album's name and unique ID.
To show all the photos in a given album, call the riya.albums.GetPhotosInAlbum method. This method requires the album_id parameter.
<?php
require_once 'riyaapi.class.php';
$r = new RiyaAPI();
$r->setApiKey(your API key);
$r->setUsername(username);
$r->setAuthToken($r->getAuthToken(password));
$response = $r->callMethod('riya.albums.GetPhotosInAlbum', array(
'album_id' => album ID,
));
if ( $response !== false ) {
echo 'Click on a photo to enlarge.';
echo '<br /><br />';
// Loop through all photos in the album
foreach ($response->album->photo as $photo) {
// Parse hoto properties
$properties = RiyaApi::parseAttributes($photo);
// Output entity
echo '<img src="' . $properties['thumbnail'] . '" alt="' . $properties['id'] . '"
onclick="this.src=\'' . $properties['screenres'] . '\';" />';
echo '<br /><br />';
}
} else {
echo 'Error Code: ' . $r->getErrorCode() . '<br />';
echo 'Error Message: ' . $r->getErrorMessage() . '<br />';
}
?>
This method returns an XML list of the image IDs for each image in the album, along with links to the image's thumbnailed and screen resolution versions.
The riya.photos.search.SearchPublic method searches through all of the images on riya.com whose permission is set to 'Public'. This is the only method in the Riya API that does not require authentication. This method takes several optional parameters:
person
Riya will try to match this parameter in a face's full_name attribute.
place
Riya will try to match this parameter in an image's tags.
text
Riya will try to match this parameter in an image's text overlays.
album
Riya will try to match this parameter in an album's name attribute
daterange
Riya will find images with dates in the specified range. The range must be in the format mm/dd/yyyy/hhmmss-mm/dd/yyyy/hhmmss.
date
Riya will find images whose date matches the specified date. The date must be in the format mm/dd/yyyy/hhmmss.
tags
Riya will try to match this parameter in an image's tags.
This method also takes three optional formatting parameters:
page
This parameter specifies the page number. The default value is 1.
per_page
This parameter specifies the number of returned images per page. The default value is 1. The maximum value is 50.
sort
This parameter specifies the sort order. The sort order can be date and time order or Riya ranking order. To specify date and time ordering, the value of the sort parameter must be date-time. To specify Riya ranking order, the value of the sort parameter must be riya-rank.
<?php
require_once 'riyaapi.class.php';
$r = new RiyaAPI();
$r->setApiKey(your API key);
$response = $r->callMethod('riya.photos.search.SearchPublic', array(
'person' => person name
));
if ( $response !== false ) {
echo 'Click on a photo to enlarge.';
echo '<br /><br />';
// Loop through all photos
foreach ($response->photos->photo as $photo) {
// Parse photo properties
$properties = RiyaApi::parseAttributes($photo);
// Output entity
echo '<img src="' . $properties['thumbnail'] . '" alt="' . $properties['id'] . '"
onclick="this.src=\'' . $properties['screenres'] . '\';" />';
echo '<br /><br />';
}
} else {
echo 'Error Code: ' . $r->getErrorCode() . '<br />';
echo 'Error Message: ' . $r->getErrorMessage() . '<br />';
}
?>
This method returns an XML list of the image IDs for each image found by the search, along with links to the image's thumbnailed and screen resolution versions.
To restrict a search to the images in your own photo collection, use the riya.photos.search.Search method. This method requires one parameter:
bucket
This mandatory parameter specifies the 'bucket' to search. This parameter can take on three values:
my-photos
This value restricts the search to your own images.
my-friends-photos
This value restricts the search to the images of users in your Contacts.
my-public-photos
This value restricts the search to images marked as 'public'
This method takes several optional parameters:
person
Riya will try to match this parameter in a face's full_name attribute.
place
Riya will try to match this parameter in an image's tags.
text
Riya will try to match this parameter in an image's text overlays.
album
Riya will try to match this parameter in an album's name attribute
daterange
Riya will find images with dates in the specified range. The range must be in the format mm/dd/yyyy/hhmmss-mm/dd/yyyy/hhmmss.
date
Riya will find images whose date matches the specified date. The date must be in the format mm/dd/yyyy/hhmmss.
tags
Riya will try to match this parameter in an image's tags.
This method also takes three optional formatting parameters:
page
This parameter specifies [asked Dan]. The default value is 1.
per_page
This parameter specifies the number of returned images per page. The default value is 1. The maximum value is 50.
sort
This parameter specifies the sort order. The sort order can be date and time order or Riya ranking order. To specify date and time ordering, the value of the sort parameter must be date-time. To specify Riya ranking order, the value of the sort parameter must be riya-rank.
<?php
require_once 'riyaapi.class.php';
$r = new RiyaAPI();
$r->setApiKey(your API key);
$r->setUsername(username);
$r->setAuthToken($r->getAuthToken(password));
$response = $r->callMethod('riya.photos.search.Search', array(
'person' => person name
));
if ( $response !== false ) {
echo 'Click on a photo to enlarge.';
echo '<br /><br />';
// Loop through all photos
foreach ($response->photos->photo as $photo) {
// Parse photo properties
$properties = RiyaApi::parseAttributes($photo);
// Output entity
echo '<img src="' . $properties['thumbnail'] . '" alt="' . $properties['id'] . '"
onclick="this.src=\'' . $properties['screenres'] . '\';" />';
echo '<br /><br />';
}
} else {
echo 'Error Code: ' . $r->getErrorCode() . '<br />';
echo 'Error Message: ' . $r->getErrorMessage() . '<br />';
}
?>
This method returns an XML list of the image IDs for each image found by the search, along with links to the image's thumbnailed and screen resolution versions.
