Ping API

Form-based request: PhotoPing.com accepts form-based HTTP GET or POST requests. (Note: if the total request length is greater than 1500 characters, you should use a POST request.)

URL: http://ping.photoping.com/ping.php

Response: An XML document. See section Return Value below for details.

Encoding: All parameter values are assumed to be UTF-8 (no conversions from other encodings, even if specified, will be performed). All parameters must be URL-encoded.

Example Requests: View source after clicking to see the XML response. Simple Request, Complex Request

Minimum Required Parameters: There are 3 required parameters. Parameters may be passed in any order.

type: Type of object. Valid values are "photo" and "video". Default is "photo".
webPageUrl: URL of the web page containing the photo (not the URL of the photo or video, see below).
(limited to a domain of 128 2-byte chars, and a path + query string of 128 2-byte chars)
title: Title of photo or video.
(limited to 128 2-byte chars)

Optional Parameters: There are 15 optional parameters. It is recommended that you pass as many of these parameters as possible so that a thumbnail of your photo or video can be displayed in the "Recent Pings" list, and so that search engines will be able to better index your photo or video.

Default values are the empty string ('') unless otherwise noted below.

Parameters may be passed in any order.

url: URL of the photo or video (not the web page where the photo/video is viewable, see above, but the URL of the actual photo or video).
(limited to a domain length of 128 2-byte chars, plus path + query string of 128 2-byte chars)
width: Width of photo or video: integer value, pixels.
height: Height of photo or video: integer value, pixels.
thumbnailUrl: URL of the thumbnail. If a thumbnail URL, height and width are specified, the thumbnail will appear next to your photo/video in the recent pings list.
(limited to a domain length of 128 2-byte chars, and a path + query string of 128 2-byte chars)
thumbnailWidth: Integer value, pixels.
thumbnailHeight: Integer value, pixels.
date: Date object was created. Date must be parseable using php's strtotime() function.
Examples: 1/27/2007 or Jan. 27, 2007 or 27 Jan. 2007 or 2007-27-01
location: Location of photo or video.
(limited to 128 2-byte chars)
Example: London, Thames Embankment
geoLocation: Latitude,longitude of photo or video.
Example: 51.508131,-0.110539
description: (limited to 255 2-byte chars)
subject: (limited to 128 2-byte chars)
tags: Comma separated list of case-insensitive tags.
(limited to 255 2-byte chars)
credit: (limited to 50 2-byte chars)
Examples: AP or Reuters or Frank Leahy
ccLicense: Which of the CC v3.0 Licenses does this photo have (if any)?
Valid values are "by" (Attribution), "by-nd" (Attribution-NoDerivs), "by-nc-nd" (Attribution-NonCommercial-NoDerivs), "by-nc" (Attribution-NonCommercial), "by-nc-sa" (Attribution-NonCommercial-ShareAlike), "by-sa" (Attribution-ShareAlike) and "other-cc-license".
adult: Is this photo or video adult in nature (i.e. pornographic or violent)? Valid values are "true" and "false". Default is "false".
(Note: You must indicate "adult=true" if your photo or video contains child inappropriate content. Failure to do so will result in your ip address, ip block, or domain being black-listed from this service.)

Return Value: The return value is an xml document that describes whether the ping was successful. The possible "status" attribute values include "ok", "error", "site-maintenance", "black-listed" and "ping-too-fast".

Successful ping: (with no errors or warnings)

<?xml version = "1.0" encoding="UTF-8" ?>
<result status="ok" />

Successful ping: (with one or more warnings)

<?xml version = "1.0" encoding="UTF-8" ?>
<result status="ok">
  <warnings>
   <warning code="80">Parameter 'date' cannot be parsed</warning>
 </warnings>
</result>

Failed ping: (with one or more errors, warnings will also be shown if found)

<?xml version = "1.0" encoding="UTF-8" ?>
<result status="error">
  <errors>
    <error code="30">Parameter 'thumbnailUrl' not a valid url</error>
  </errors>
</result>

Maintenance window:
```
<?xml version = "1.0" encoding="UTF-8" ?>
<result status="site-maintenance" />
```
Note: If the site is undergoing maintenance, please wait for at least 120 seconds before attempting another ping.
Black-listed: your url, domain or ip address has been black-listed
```
<?xml version = "1.0" encoding="UTF-8" ?>
<result status="black-listed" />
```
Note: We would really prefer not to have to monitor the service for abuse. Please follow the Terms & Conditions and we'll all be happy.
Ping too fast: you are pinging more often than every 15 seconds, please slow down
```
<?xml version = "1.0" encoding="UTF-8" ?>
<result status="ping-too-fast" />
```
Note: If you need to be able to ping more often than every 15 seconds, please contact us.

Ping Output: Ping output currently takes forms:

Recent Pings as displayed on the front door
Last 5 minutes worth of pings in RSS format (updated every 5 minutes)
Last 60 minutes worth of pings in RSS format (updated every hour)
Last 24 hours worth of pings in RSS format (updated after midnight GMT)
Last 5 minutes worth of pings in PhotoRSS format (updated every 5 minutes)
Last 60 minutes worth of pings in PhotoRSS format (updated every hour)
Last 24 hours worth of pings in PhotoRSS format (updated after midnight GMT)

Ping output is cached for either 5 minutes, 60 minutes, or 24 hours. You must check the "Last-Modified:" response header returned when you request these files, and make a conditional GET using an "If-Modified-Since:" header before requesting the complete file again.

Error Codes:

errors['1'] = "Object 'type' not one of {photo|video}"
errors['10'] = "'webPageUrl' required"
errors['11'] = "'webPageUrl' not a valid url"
errors['12'] = "'webPageUrl' doesn't begin with http:// or https://"
errors['13'] = "'webPageUrl' has no path"
errors['14'] = "'webPageUrl' domain > 128 characters"
errors['15'] = "'webPageUrl' path + query string > 128 characters"
errors['16'] = "'webPageUrl' cannot be an ip address"
errors['20'] = "'title' required"
errors['31'] = "Object 'url' not a valid url"
errors['32'] = "Object 'url' does not begin with http:// or https://
errors['33'] = "Object 'url' has no path"
errors['34'] = "Object 'url' domain > 128 characters"
errors['35'] = "Object 'url' path + query string > 128 characters"
errors['36'] = "Object 'url' domain domain cannot be an ip address";
errors['40'] = "Object 'height' not a number"
errors['42'] = "Object 'width' not a number"
errors['51'] = "'thumbnailUrl' not a valid url"
errors['52'] = "'thumbnailUrl' does not begin with http:// or https://"
errors['53'] = "'thumbnailUrl' has no path"
errors['54'] = "'thumbnailUrl' domain > 128 characters"
errors['55'] = "'thumbnailUrl' path + query string > 128 characters"
errors['56'] = "'thumbnailUrl' cannot be an ip address"
errors['60'] = "'thumbnailHeight' not a number"
errors['61'] = "'thumbnailHeight' too small (must be >= 10)"
errors['62'] = "'thumbnailHeight' too large (must be <= 250)"
errors['63'] = "'thumbnailWidth' not a number"
errors['64'] = "'thumbnailWidth' too small (must be >= 10)"
errors['65'] = "'thumbnailWidth' too large (must be <= 250)"
errors['66'] = "'thumbnailHeight' or 'thumbnailWidth' invalid so thumbnail cannot be displayed"
errors['70'] = "'date' cannot be parsed"
errors['90'] = "'geoLocation' not of the form 'latitude,longitude'"
errors['91'] = "'geoLocation.latitude' not a number"
errors['92'] = "'geoLocation.longitude' not a number"
errors['93'] = "'geoLocation.latitude' >360 or <-360 and will be ignored"
errors['94'] = "'geoLocation.longitude' >360 or <-360 and will be ignored"
errors['140'] = "'ccLicense' not one of {by|by-nd|by-nc-nd|by-nc|by-nc-sa|by-sa|other}"
errors['150'] = "'commercial' not one of {true|false}"
errors['160'] = "'forSale' not one of {true|false}"
errors['170'] = "'adult' not one of {true|false}"

Warning Codes:

warnings['21'] = "'title' will be truncated to 128 2-byte characters"
warnings['30'] = "Object 'url' not specified"
warnings['41'] = "Object 'height' not specified"
warnings['43'] = "Object 'width' not specified"
warnings['50'] = "'thumbnailUrl' not specified"
warnings['80'] = "'location' will be truncated to 128 2-byte characters"
warnings['100'] = "'description' will be truncated to 255 2-byte characters"
warnings['110'] = "'subject' will be truncated to 128 2-byte characters"
warnings['120'] = "'tags' will be truncated to 255 2-byte characters"
warnings['121'] = "One or more 'tags' will be truncated to 50 2-byte characters"
warnings['130'] = "'credit' will be truncated to 128 2-byte characters"