XML-RPC API

← Back

Connecting
API Endpoint: https://secure.gravatar.com/xmlrpc?user=[email_hash]

It is mandatory that you connect to secure.gravatar.com, and that you do so over HTTPS. This is for the safety of our mutual users. The email_hash GET parameter is the md5 hash of the users email address after it has been lowercased, and trimmed.

All parameters for all methods should be passed as a single item, within an associative array.

Authentication
User authentication happens at the api method level. You will pass to the method call a password parameter. The data for these parameters will be passed in plain text. The password param is always stripped from the arguments before the methods begin their processing. For this reason you should expect not to see it returned from the grav.test method.

Errors
Errors usually come with a number and human readable text. Generally the text should be followed whenever possible, but a brief description of the numeric error codes are as follows:

	-7	Use secure.gravatar.com 
	-8	Internal error 
	-9	Authentication error 
	-10	Method parameter missing 
	-11	Method parameter incorrect 
	-100	Misc error (see text) 

Methods
grav.exists - check whether a hash has a gravatar 
	@param  (array)$args['hashes'] an array of hashes to check 
	@param	(string)$args['password'] for authentication 
	@return array ( 
		hash => (bool)exists,
	)

grav.addresses - get a list of addresses for this account 
	@param  (string)$args['password'] for authentication 
	@return array ( 
		address => array (
			rating        => (int)rating, 
			userimage     => (int)userimage, 
			userimage_url => (int)userimage_url
		) 
	)

grav.userimages - return an array of userimages for this account 
	@param  (string)$args['password'] for authentication 
	@return array (
		userimage => array( 
			(int)rating, // 0:g, 1:pg, 2:r, 3:x
			(string)url,
		)
	) 

grav.saveData - Save binary image data as a userimage for this account 
	@param  (string)$args['data'] a base64_encode()d image
	@param  (int)$args['rating'] 0:g, 1:pg, 2:r, 3:x
	@param  (string)$args['password'] for authentication 
	@return (bool)false on failure, (string)userimage on success 

grav.saveUrl - Read an image via its URL and save that as a userimage for this account 
	@param  (string)$args['url'] a full url to an image 
	@param  (int)$args['rating'] 0:g, 1:pg, 2:r, 3:x
	@param  (string)$args['password'] for authentication 
	@return (bool)false on failure, (string)userimage on success 

grav.useUserimage - use a userimage as a gravatar for one of more addresses on this account 
	@param  (string)$args['userimage'] The userimage you wish to use 
	@param  (array)$args['addresses'] A list of the email addresses you wish to use this userimage for 
	@param  (string)$args['password'] for authentication 
	@return array(
		address => (bool)status
	)

grav.removeImage - remove the userimage associated with one or more email addresses 
	@param  (array)$args['addresses'] A list of the email addresses you wish to use this userimage for 
	@param  (string)$args['password'] for authentication 
	@return array(
		address => (bool)status
	)

grav.deleteUserimage - remove a userimage from the account and any email addresses with which it is associated 
	@param  (string)$args['userimage'] The userimage you wish to remove from the account 
	@param  (string)$args['password'] for authentication 
	@return (bool)status

grav.test - a test function
	@param  (string)$args['password'] for authentication 
	@return (mixed)$args