Photos

Photos

SAPO Fotos is a completely free pictures service aimed at hosting, managing and sharing your photographs with your friends and relatives.

Free subscription

Technical Overview

Photos Service

Search of photos. In this service you can search for photos of a user, a tag, or both simultaneously. It also allows searching for an user photos album.

API Reference

Service Operation Description
Photos AlbumCreate Creates an album in the Fotos platform.
AlbumGetListByCollection Returns an array of Albums for a given collection.
AlbumGetListByHighlighted Returns a list of featured albums for a given interface (default is fotos.sapo.pt).
AlbumGetListByUser Returns a list of albums for a particular user (special album 'Ao Molho', as well as the rest, except the album 'Favoritos' that will have its own methods).
CollectionGetListByUser Returns an array of collections for a given user.
DummyEcho Provides an echo, for testing purposes. Use this to test the API access in production. If the optional parameter is specified, it is appended in the result to the timestamp returned.
ImageAddToAlbum Adds an image to one or more albums of the same user.
ImageCreate

Creates an image in the Fotos platform.

The image upload through the Fotos API is a two step process.

  • First you need to call the ImageCreate method with the meta-info related to the image. This method returns, along with more image related platform-specific information, a token which you will have to use as the 'token' named parameter passed on step 2.
  • Second you need to do a POST call to http://fotos.sapo.pt/uploadPost.html, along with the image file. This token's TTL is 10 minutes, which should give you more than enough time to complete the whole process. The file to be sent via POST does not need a specific name for it input file type, any can be used.
ImageDelete Deletes an Image from the service
ImageDetails Image metadata details.
ImageEdit Edits an image on the Fotos platform. Invoke the method ImageEdit with the meta-information corresponding to the image. This method returns the image with the updated meta-information that was sent by the user.
ImageGetListBySearch Searches the Fotos database for images related to the search terms.
ImageGetListByTags Gets a list of images marked with the given tags. It is also possible to narrow it down to a specific user, specify m18 access and the order of the list.
ImageGetListByUser Returns a list of images from a particular user.
ImageGetListByUserAlbum Returnsa list of images for a specific user/album pair.
ImageNotifyView Notifies the platform that an image visualization has occurred. Administrator permissions are required.
ImageRemoveFromAlbum Removes an image from a given list of albums.
JSON Search of public photos tagged with the expression “sol” in JSON format
RSS Search of public photos tagged with the expression “sol” in RSS format
TagsGetListByHighlighted Fetch a list of current highlighted tags
UserCreate Creates a user in the SAPO Fotos platform
UserDetails Returns the account details of an user of the Fotos platform.
UserGetListByHighlighted Returns the list of users in highligh for a given interface (default is: fotos.sapo.pt).
UserGetTags Returns a list of tags used by a particular user.

Photos Service

Operations

AlbumCreate

Creates an album in the Fotos platform.
Request Parameters
album : Album (required)
Response Parameters
AlbumCreateResult : AlbumCreateResult (required)

Returns an instance of type Album.

This method returns the album url, as well as the link for future cover.

Go to top

AlbumGetListByCollection

Returns an array of Albums for a given collection.
Request Parameters
collection : Collection (required)
page : int (optional)
orderBy : string (optional)
Response Parameters
AlbumGetListByCollectionResult : AlbumGetListByCollectionResult (required)

Returns an instance of type ArrayOfAlbums.

This method does not return any information about the images in the albums returned.

Go to top

AlbumGetListByHighlighted

Returns a list of featured albums for a given interface (default is fotos.sapo.pt).
Request Parameters
page : int (optional)

The page number to obtain (1-based).

orderBy : string (optional)

The orderBy field may take the following values​​:

  • alfabeticamente (alphabetically)
  • alfabeticamente-inversa (reverse-alphabetically)
  • maisantigas (oldest pictures)
  • maisantigos (oldest albuns, sets)
  • maisrecentes (newers)
  • relevancia (relevance)
  • id (identifier)
intf : string (optional)

Interface to which you want to get the highlights (default: fotos.sapo.pt)

Response Parameters
AlbumGetListByHighlightedResult : AlbumGetListByHighlightedResult (required)

Returns an instance of type ArrayOfAlbums.

This method does not return any information about the images in the albums returned.

Go to top

AlbumGetListByUser

Returns a list of albums for a particular user (special album 'Ao Molho', as well as the rest, except the album 'Favoritos' that will have its own methods).
Request Parameters
user : User (required)

It's not necessary to fill this parameter if the credentials user is the owner of the album.

page : int (optional)

The page number to obtain (1-based).

orderBy : string (optional)

The orderBy field may take the following values​​:

  • alfabeticamente (alphabetically)
  • alfabeticamente-inversa (reverse-alphabetically)
  • maisantigas (oldest pictures)
  • maisantigos (oldest albuns, sets)
  • maisrecentes (newers)
  • relevancia (relevance)
  • id (identifier)
interface : string (optional)

Interface to which you want to get the highlights (default: fotos.sapo.pt)

Response Parameters
AlbumGetListByUserResult : AlbumGetListByUserResult (required)

Returns an instance of type ArrayOfAlbums.

This method does not return any information about the images in the albums returned.

Go to top

CollectionGetListByUser

Returns an array of collections for a given user.
Request Parameters
user : User (required)
You only need to fill in the username.
page : int (optional)

The page number to obtain (1-based).

orderBy : string (optional)

The orderBy field may take the following values​​:

  • alfabeticamente (alphabetically)
  • alfabeticamente-inversa (reverse-alphabetically)
  • maisantigas (oldest pictures)
  • maisantigos (oldest albuns, sets)
  • maisrecentes (newers)
  • relevancia (relevance)
  • id (identifier)
Response Parameters
CollectionGetListByUserResult : CollectionGetListByUserResult (required)

Returns an instance of type ArrayOfCollections

Go to top

DummyEcho

Provides an echo, for testing purposes. Use this to test the API access in production. If the optional parameter is specified, it is appended in the result to the timestamp returned.
Request Parameters
echoStr : string (optional)

Receives a string as an optional parameter.

Response Parameters
DummyEchoResult : string (required)

Returns a string with a timestamp and the text sent as input parameter.

Go to top

ImageAddToAlbum

Adds an image to one or more albums of the same user.
Request Parameters
image : Image (required)

Should be specified as many albums as you want to add to the image. Should be necessarily added the attributes 'Image:: uid' and 'Album: id'.

interface : string (optional)

Interface to which you want to get the highlights (default: fotos.sapo.pt)

Response Parameters
ImageAddToAlbumResult : ImageAddToAlbumResult (required)

Returns only the type result.

Go to top

ImageCreate

Creates an image in the Fotos platform.

The image upload through the Fotos API is a two step process.

  • First you need to call the ImageCreate method with the meta-info related to the image. This method returns, along with more image related platform-specific information, a token which you will have to use as the 'token' named parameter passed on step 2.
  • Second you need to do a POST call to http://fotos.sapo.pt/uploadPost.html, along with the image file. This token's TTL is 10 minutes, which should give you more than enough time to complete the whole process. The file to be sent via POST does not need a specific name for it input file type, any can be used.
Request Parameters
image : Image (required)

It's not mandatory to fill any attributes, although it is a good idea to fill at least the following:

  • title
  • synopsis
  • tags (for now any 'space', ';' or ',' separate tags - to use several words in the same tag, use underscore'_')
interface : string (optional)

Interface to which you want to get the highlights (default: fotos.sapo.pt)

Response Parameters
ImageCreateResult : ImageCreateResult (required)

Returns an instance of type Image with more meta-info about the image and also a string with a token. The last one should be used to complete the upload process.

Examples

POST call of 2nd step of creating an image

The parameter "redir" is optional.

If in this POST call, an URL is specified in parameter 'redir', instead of be returned a XML, the URL will be invoked, and the identifier of the call result will be sent in attribute 'status', by get.

Here is the typification of the returned identifiers:

Identificador Descrição Observações
INVALID_UPLOAD Invalid upload, possibly max upload size of xxxxx bytes exceeded
MISSING_TOKEN Missing token from POST vars não foi enviado nada no atributo 'token'
INVALID_TOKEN Invalid token o token enviado via POST é inválido
INVALID_IMAGE Invalid image referenced by token
INVALID_OWNER Invalid owner, user is probably banned
EXHAUSTED_TOKEN Token exhausted o token já foi utilizado
NO_FILE No file was sent não foi enviado um ficheiro de imagem
FILE_COUNT_EXCEEDED Only allowed to upload one file at a time foi enviado mais que um ficheiro de imagem
INVALID_FILE Invalid file for upload o ficheiro enviado não é válido (não tem a ver com formatos da imagem, mas sim com a correcta formatação do request e do ficheiro no envio)
FILE_LIMIT_QUOTA_EXCEEDED User exceeded maximum allowed total of images of xxxx
FILE_SIZE_QUOTA_EXCEEDED User exceeded file quota size of xxxx
TOTAL_STORAGE_QUOTA_EXCEEDED User exceeded total storage quota of xxxx
INVALID_DIMENSIONS File does not fulfill minimum dimensions requirements of ??x??
PROBLEMS_SAVING_IMAGE Problems saving image. Contact the tech support houve um erro ao gerar uma ou mais dimensões da imagem original. É possível que a mesma esteja em estado de erro na plataforma
SUCCESS sucesso

Following is an example of HTML code for the second step of loading an image through API Photos (upload image), where the parameter "redir" - as mentioned above - is optional.

XML response format

On success: In case of error:
Go to top

ImageDelete

Deletes an Image from the service
Request Parameters
image : Image (required)

The attribute 'Image:: uid' must always be filled.

Response Parameters
ImageDeleteResult : Result (required)
Go to top

ImageDetails

Image metadata details.
Request Parameters
image : Image (required)

The attribute 'Image::uid' must always be filled.

Response Parameters
ImageDetailsResult : ImageDetailsResult (required)
An object of type Image, filled with the remaining details of the image.
Go to top

ImageEdit

Edits an image on the Fotos platform. Invoke the method ImageEdit with the meta-information corresponding to the image. This method returns the image with the updated meta-information that was sent by the user.
Request Parameters
image : Image (required)

You must have the 'Image:: uid' filled as a way of identifying the image to be edit. It isn't mandatory to fill any other attributes.

Fields available for update are as follows:

  • Image::title
  • Image::active
  • Image::password
  • Image::m18
  • Image::synopsis
  • Image::tags (for now any 'space', ';' or ',' separate tags - to use several words in the same tag, use underscore '_')
Response Parameters
ImageEditResult : ImageEditResult (required)

Returns an instance of type Image with updated meta-info.

NOTE: The meta-information of the image will be replaced by the meta-information sent in the input parameter, so you should be aware that fields left blank will remove any information that existed before.

Go to top

ImageGetListBySearch

Searches the Fotos database for images related to the search terms.
Request Parameters
page : int (optional)

The page number to obtain (1-based).

interface : string (optional)

Interface to which you want to get the highlights (default: fotos.sapo.pt)

terms : ArrayOfStrings (required)
One or more string for search in description/tags.
dateFrom : string (optional)

Minor date limit for search by date.

Format: It is best to use yyyy-mm-dd, but all PHP function strtotime formats are supported (http://www.php.net/strtotime).

dateTo : string (optional)

Upper date limit for searching by date.

Format: It's best to use yyyy-mm-dd, but all PHP function strtotime formats are supported.

Response Parameters
ImageGetListBySearchResult : ImageGetListBySearchResult (required)
Returns an instance of type ArrayOfImages.
Go to top

ImageGetListByTags

Gets a list of images marked with the given tags. It is also possible to narrow it down to a specific user, specify m18 access and the order of the list.
Request Parameters
tags : ArrayOfTags (required)
An array of tags.
page : int (optional)
The page number to obtain (1-based).
orderBy : string (optional)

The orderBy field may take the following values​​:

  • alfabeticamente (alphabetically)
  • alfabeticamente-inversa (reverse-alphabetically)
  • maisantigas (oldest pictures)
  • maisantigos (oldest albuns, sets)
  • maisrecentes (newers)
  • relevancia (relevance)
  • id (identifier)
m18 : boolean (optional)
user : User (optional)
Fill user:username to het images of tags of that user.
interface : string (optional)
Interface to which you want to get the highlights (default: fotos.sapo.pt)
Response Parameters
ImageGetListByTagsResult : ImageGetListByTagsResult (required)
Go to top

ImageGetListByUser

Returns a list of images from a particular user.
Request Parameters
page : int (optional)
The page number to obtain (1-based).
user : User (required)
It's not necessary to fill this parameter if the credentials user is the desired user.
Response Parameters
ImageGetListByUserResult : ImageGetListByUserResult (required)
Returns an instance of type ArrayOfImages.
Go to top

ImageGetListByUserAlbum

Returnsa list of images for a specific user/album pair.
Request Parameters
user : User (required)
It's not necessary to fill this parameter if the credentials user is the album owner.
album : Album (required)
page : int (optional)
O número da página a obter (1-based).
interface : string (optional)
Interface to which you want to get the highlights (default: fotos.sapo.pt)
orderBy : string (optional)

The orderBy field may take the following values​​:

  • alfabeticamente (alphabetically)
  • alfabeticamente-inversa (reverse-alphabetically)
  • maisantigas (oldest pictures)
  • maisantigos (oldest albuns, sets)
  • maisrecentes (newers)
  • relevancia (relevance)
  • id (identifier)
Response Parameters
ImageGetListByUserAlbumResult : ImageGetListByUserAlbumResult (required)
Returns an instance of type ArrayOfImages.
Go to top

ImageNotifyView

Notifies the platform that an image visualization has occurred. Administrator permissions are required.
Request Parameters
value : int (required)
type : string (optional)
image : Image (required)
Response Parameters
ImageNotifyViewResult : ImageNotifyViewResult (required)
Go to top

ImageRemoveFromAlbum

Removes an image from a given list of albums.
Request Parameters
image : Image (required)
Should be specified as many albums as you want to remove the image from, at most 50. Must fill the attributes 'Image::uid' and 'Album::id'.
Response Parameters
ImageRemoveFromAlbumResult : Result (required)
Go to top

JSON

Search of public photos tagged with the expression “sol” in JSON format
Examples

Search of public photos tagged with the expression “sol” in JSON format

Search of public photos from user “celso” in JSON format

Search of public photos from user “celso” tagged with the expression “jobs” in JSON format
Go to top

RSS

Search of public photos tagged with the expression “sol” in RSS format
Examples

Search of public photos tagged with the expression “sol” in RSS format

Search of public photos from user “celso” in RSS format

Search of public photos from use “celso” tagged with the expression “jobs” in RSS format

Search of public photos in RSS format

Search of public photos from user “celso” with pagination in RSS format
Go to top

TagsGetListByHighlighted

Fetch a list of current highlighted tags
Request Parameters
intf : string (optional)
Response Parameters
TagsGetListByHighlightedResult : TagsGetListByHighlightedResult (optional)
Go to top

UserCreate

Creates a user in the SAPO Fotos platform
Request Parameters
user : User (required)
Response Parameters
UserCreateResult : UserCreateResult (required)

Returns an instance of type User.

In the result, is returned a link to the profile page and a link to the avatar.

Go to top

UserDetails

Returns the account details of an user of the Fotos platform.
Request Parameters
user : User (required)
It's not necessary to fill this parameter if the credentials user is the desired user.
interface : Format (optional)
Interface to which you want to get the highlights (default: fotos.sapo.pt)
Response Parameters
UserDetailsResult : UserDetailsResult (required)
Returns an instance of type User.
Go to top

UserGetListByHighlighted

Returns the list of users in highligh for a given interface (default is: fotos.sapo.pt).
Request Parameters
page : int (optional)
The page number to obtain (1-based).
orderBy : string (optional)

The orderBy field may take the following values​​:

  • alfabeticamente (alphabetically)
  • alfabeticamente-inversa (reverse-alphabetically)
  • maisantigas (oldest pictures)
  • maisantigos (oldest albuns, sets)
  • maisrecentes (newers)
  • relevancia (relevance)
  • id (identifier)
intf : string (optional)
Interface to which you want to get the highlights (default: fotos.sapo.pt)
Response Parameters
UserGetListByHighlightedResult : UserGetListByHighlightedResult (required)
Returns an instance of type ArrayOfUser.
Go to top

UserGetTags

Returns a list of tags used by a particular user.
Request Parameters
user : User (required)
It's not necessary to fill this parameter if the credentials user is the desired user.
interface : string (optional)
Interface to which you want to get the highlights (default: fotos.sapo.pt)
Response Parameters
UserGetTagsResult : UserGetTagsResult (required)

Returns an instance of type ArrayOfTags.

The list of tags doesn't has any kind of order.

Go to top

Photos Entities

Album

Attribute Name Description
id : int (optional)
ownerId : int (optional)
active : boolean (optional)
password : string (optional)
creationDate : string (optional)
description : string (optional)
title : string (optional)
url : string (optional)
user : User (optional)
cover : string (optional)
Go to top

AlbumCreateResult

Attribute Name Description
result : Result
album : Album (optional)
Go to top

AlbumGetListByCollectionResult

Attribute Name Description
result : Result
albums : ArrayOfAlbums (optional)
Go to top

AlbumGetListByHighlightedResult

Attribute Name Description
result : Result
albums : ArrayOfAlbums (optional)
Go to top

AlbumGetListByUserResult

Attribute Name Description
albums : ArrayOfAlbums (optional)
result : Result
Go to top

ArrayOfAlbums

Attribute Name Description
List of album : Album (optional)
Go to top

ArrayOfCollections

Attribute Name Description
List of collection : Collection
Go to top

ArrayOfComments

Attribute Name Description
List of comment : Comment (optional)
Go to top

ArrayOfImages

Attribute Name Description
List of image : Image
Go to top

ArrayOfStrings

Attribute Name Description
List of string : string
Go to top

ArrayOfTags

Attribute Name Description
List of tag : string (optional)
Go to top

ArrayOfUsers

Attribute Name Description
List of user : User
Go to top

ArrayOfViews

Attribute Name Description
List of view : View (optional)
Go to top

Collection

Collection object.
Attribute Name Description
id : int (optional)
active : boolean (optional)
creationDate : string (optional)
description : string (optional)
title : string (optional)
user : User (optional)
code : string (optional)
cover : string (optional)
url : string (optional)
Go to top

CollectionGetListByUserResult

Attribute Name Description
result : Result
collections : ArrayOfCollections (optional)
Go to top

Color

Attribute Name Description
red : int
green : int
blue : int
Go to top

Comment

Attribute Name Description
date : string
nickname : string
website : string
body : string
Go to top

Format

Value Name Description
jpeg
jpg
bmp
gif
png
tiff
tif
Go to top

Image

Attribute Name Description
id : int (optional)
active : boolean (optional)
password : string (optional)
creationDate : string (optional)
pending : boolean (optional)
uid : string (optional)
subtitle : string (optional)
synopse : string (optional)
title : string (optional)
url : string (optional)
rating : string (optional)
tags : string (optional)
comments : ArrayOfComments (optional)
m18 : boolean (optional)
innapropriate : boolean (optional)
format : Format (optional)
albums : ArrayOfAlbums (optional)
user : User (optional)
emailFrom : string (optional)
visualizations : int (optional)
views : ArrayOfViews (optional) An array with View objects
refColor : Color (optional) The reference RGB color of the image
avgColor : Color (optional) The single average RGB color of the image
Go to top

ImageAddToAlbumResult

Attribute Name Description
result : Result
Go to top

ImageCreateResult

Attribute Name Description
token : string (optional) A token that should be used to upload the actual image file afterwards
image : Image (optional)
result : Result
Go to top

ImageDetailsResult

Attribute Name Description
result : Result
image : Image (optional)
Go to top

ImageEditResult

Attribute Name Description
result : Result
image : Image (optional) The altered image
Go to top

ImageGetListBySearchResult

Attribute Name Description
result : Result
images : ArrayOfImages (optional)
Go to top

ImageGetListByTagsResult

Attribute Name Description
result : Result
images : ArrayOfImages (optional)
Go to top

ImageGetListByUserAlbumResult

Attribute Name Description
result : Result
images : ArrayOfImages (optional)
Go to top

ImageGetListByUserResult

Result object for the ImageGetListByUser method
Attribute Name Description
result : Result
images : ArrayOfImages (optional)
Go to top

ImageNotifyViewResult

Attribute Name Description
result : Result
Go to top

Result

Object for pagination help

Attribute Name Description
total : int (optional) The total number of items existing at the server-side - not the total of items returned in the result.
page : int (optional) The current page to which the result belongs.
totalPages : int (optional) The total number of pages for the universe of existing results in the server-side.
perPage : int (optional) The number of items per page.
ok : boolean Specifies the success or failure of the outcome.
description : string (optional) Description of the outcome, mostly used for errors.
Go to top

TagsGetListByHighlightedResult

Attribute Name Description
result : Result (optional)
tags : ArrayOfTags (optional)
Go to top

User

Attribute Name Description
id : int (optional)
active : boolean (optional)
banned : boolean (optional)
commentCaptcha : boolean (optional)
commentModerate : boolean (optional)
commentNotify : boolean (optional)
creationDate : string (optional)
email : string (optional)
lastLogin : string (optional)
partner : boolean (optional)
uploadMail : string (optional)
username : string (optional)
viewAll : boolean (optional)
avatar : string (optional)
url : string (optional)
imageCount : int (optional)
albumCount : int (optional)
Go to top

UserCreateResult

Attribute Name Description
result : Result
user : User (optional)
Go to top

UserDetailsResult

Attribute Name Description
result : Result
user : User (optional)
Go to top

UserGetListByHighlightedResult

Attribute Name Description
result : Result
users : ArrayOfUsers (optional)
Go to top

UserGetTagsResult

Attribute Name Description
tags : ArrayOfTags (optional)
result : Result
Go to top

View

Attribute Name Description
actualWidth : int (optional)
actualHeight : int (optional)
requestWidth : int (optional)
requestHeight : int (optional)
url : string
size : string The textual description of the format
Go to top

REST API Authentication

Authenticating REST Request

Every request must contain authentication information to establish the identity of whom making the request and a autorization token denominated ESBAccessKey.

ESB Access Key

The ESB Access Key is what will authorize the usage of the API and is available when the buying process ends. In the costumer area you can find the product details where you can generate an ESB Access Key for you usage, another user registered on SAPO Services or even for everyone.

The element ESBAccessKey must appear on the URL as a query-string

HTTP GET example using username and password:

HTTP POST username and password:

Request with ESBToken

Using a token instead of your username and password can be useful if you don't want to give your credentials to whom is using the API.

In order to generate a ESB Token you must use SAPO Security Token Service. The ESBToken is valid for 12 hours.

HTTP GET example using ESB Token:

HTTP POST ESB Token:

Parameters description

ESBCredentials are parameters used to authenticate and authorize a REST request

Elements Description
ESBUsername The e-mail of the account that is used to access the API.
ESBPassword The password that in combination with the ESBUsername is used to access the corresponding account.
ESBToken An authentication token generated by using an user name (ESBUsername) and password (ESBPassword). It should be used a ESBToken or the combination of ESBUsername and ESBPassword.
ESBAccessKey The authorization key used to authorize the request against your purchase. The account being used to access the service must be associated to this key.
Go to top

SOAP API Authentication

Authenticating SOAP Request

Every request must contain authentication information to establish the identity of whom making the request and a autorization token called ESB Access Key.

ESB Access Key

Correct with the path to the access key

The ESB Access Key is what will authorize the usage of the API and is available when the buying process ends. In the costumer area you can find the product details where you can generate an ESB Access Key for you usage, another user registered on SAPO Services or even for everyone.

The element ESBAccessKey must appear on the message SOAP Header after the complex type ESBCredentials

Example:

ESBCredentials

ESBCredentials is a complex type that is used to pass the credentials in order to authenticate a SOAP request.

Request with username and password
Elements Description
ESBUsername The e-mail of the account that is used to access the API
ESBPassword The password that in combination with the ESBUsername is used to access the corresponding account

Example:

Request with ESBToken

Using a token instead of your username and password can be useful if you don't want to give your credentials to whom is using the API.

In order to generate a ESB Token you must use SAPO Security Token Service (STS). The ESBtoken is valid for 12 hours.

Requesting with an ESBtoken
Go to top