Pond5 API

If you have questions/feedback; do not hesitate to .

The Pond5 API is for another software using the Pond5 functionality as opposed to a human user. The reason for this could for example be to create an iPhone application.

We currently have two means of integrating our data into your software/website:

* The API
* https://www.pond5.com/document/xml_search.html

The https://www.pond5.com/document/xml_search.html does not require authentication, but thereby lacks complex functionality as the api provides.


To use the API your Pond5 account need to be configured for it in the database. This configuration consists of two important things, api_key and my_secret. The api_key identifies you and my_secret is used to authenticate a request.
to get an api_key and my_secret setup for your account.

To avoid implementing the low level protocol, we provide a PHP client library
If you want to use any other language, or want to created your own php implementation, the protocol is described after the PHP library below.


The Pond5 PHP lib depends on curl being compiled into PHP. You should also consider using at least PHP version 5.2.0 or higher since it has http://pecl.php.net/package/json.

* https://www.pond5.com/files/api_client.zip.

require_once ("p5api_client/p5api_client_v1.php")

The v1 thing is what version of the API. If the API changes in a way so that it's too different for it to be a point in having all the code in the same file, a new version will be created. As long as you stick to the same version, your code should not have to change.

$client = new p5api_client();
$client->api_key = "234_345";
$client->my_secret = "something";

$cmd = $client->get_search_command();
$cmd->col_mask = p5api_client_command_search::$COL_NAME + p5api_client_command_search::$COL_DURATION;
$cmd->query = "dog";

$obj = $client->query_pond5();

$apa = $client->get_flv($json["commands"][0], $json["commands"][0]["items"][0], 480, 270);
PHP does not have enums which (when it exists) is an excellent way of having extra compile time security. As a workaround to this, the p5api_client class has capitalized constants defined. The commands are named CMD_something, your http://netbeans.org/features/php/index.html should give you the various options when you start entering p5api_client_command::$CMD_.

* https://www.pond5.com/files/search_api.txt You can https://www.pond5.com/examples/search_api.php.
* https://www.pond5.com/files/search_response.txt
* https://www.pond5.com/files/search_response.xml

Note: The API currently does NOT allow search for photos / illustrations, even though the php lib has constants for these types.

API Protocol

If you want to use any other language, or want to create your own php implementation, you will use the API protocol directly.

Quick links for the reference documentation and sample code using the api directly:

* https://www.pond5.com/index.php?page=api_ref_doc
* https://www.pond5.com/files/api_example01.txt
* https://www.pond5.com/files/api_example02.txt

Data is communicated through JSON or XML posted over http. If first character is { it's assumed to be JSON by the server side.

The api will respond with content of Content-Type: application/json

The JSON and XML are similar, but obviously a different structure.
We will describe the JSON structure here, if you prefer XML, read this documentation and study a https://www.pond5.com/document/api_example_xml.html to see the similarity.

You need to build together your JSON struct and post it as argument api=(your struct) to http://www.pond5.com/?page=api or https://www.pond5.com/?page=api.

An example of the "login" command posted, and the response recieved.

We make a POST to the url https://www.pond5.com/?page=api

The POST consist of one parameter "api", that we set to the following JSON data

{ "api_key" : "19284_9313763727",
  "commands_hash" : "9ecf81a86cb9ccca063607994bcf969e",
  "commands_json" : "[{\"command\":\"login\",\"username\":\"someusername\",\"password\":\"blahblah\"}]",
  "ver" : 1

"api_key" is the key that you recieved from us

"ver" is which version of the API to use (at the moment we have only version 1, so always set this to 1)

"commands_json" consist of "command" which tell the server which command to execute, and then there might be aditional arguments that that command needs

"commands_hash" Is the JSON string of the commands_json concatted with your apisecret and appended with the string 'dragspel', and then md5 is executed on that long string. The returned result is commands_hash.
E.g. for this example the string would look like this

where "asdgadghkHJG" is the api secret you recieved from us,
and md5 executed on that string will give "9ecf81a86cb9ccca063607994bcf969e".

The purpose of the commands_hash is to prevent abuse of the API.

The response from the Pond5 server would be
{ "commands" : [ { "e" : true,
        "s" : "Command #0: failed to find user [someusername]"
      } ],
  "e" : false

On a successful "login" command, two values "cx" and "cm" will be returned in the result. These need to be passed along in each request if you want to perform action as that user.
I.e. the post values will than be api, apicm, apicx. See examples linked above.


The API supports (at the time of this writing) requests of more than one command at once. This is to reduce latency.
	"api_key" : "123_456",
	"ver" : 1,
	"commands_hash" : "asdasdasd",
	"commands_json" : "[...]"
commands_json is a json encoded array of commands. commands_hash is an authentication of the commands_json string.

A command looks like
	"command" : "..."
The rest (when this is written) depends on what command it is.

command "search"

	"command" : "search",
	"query" : "...",
	"bm" : ...,
	"sb" : ...,
	"no" : ...,
	"p" : ...,
	"col" : ...

query : only needed if non empty string.
bm : (bitmask) what types of clips to return. see fake enum p5api_client_command::$BM_...
sb :sort by. see fake enum p5api_client_command::$SB_...
no : nbr of clips per page
p : at what page? 0..
col : bitmask of which columns apart from id, vs, ox, oy caller wants.

see https://www.pond5.com/index.php?page=api_ref_doc#search for more information about what arguments the search command accepts.


On root level error (authentication failed etc):
	"e" : true,
	"s" : "string describing the error"
Note:Right now all errors are on root level.

Normal responses:
	"e" : false,
	"commands" : [...]
Where commands is an array of command_responses.

How a command_response looks like depends on what command it is a response to. A command response with an error looks the same as on root level:
	"e" : true,
	"s" : "string describing the error"

Command_response for search:
	"tot_nbr_rows" : ...,
	"nbr_footage" : ...,
	"nbr_music" : ...,
	"nbr_sfx" : ...,
	"icon_base" : ...,
	"flv_base" : ...,
	"items" : [...]
tot_nbr_rows : total number of hits on Pond5. The other nbr_ are in the subset of 2000 clips that the search engine limits to internally.
icon_base : The icons shoud be fetched here.
flv_base : The flvs and preview movs should be fetched here.
items : array of
	"id" : ...,
	"vs" : ...,
	"ar" : ...,
	"ox" : ...,
	"oy" : ...,
	// below by setting "col" bitmask
	"n" : "...",
	"dur" : ...,
	"kw" : "..."
"id" is the id of the clip.
"n" is the name of the clip.
"vs" is the video_standard 
  0  - Multimedia / Unknown
  1  - NTSC D1
  2  - NTSC DV
  3  - PAL / PAL DV
  4  - HD 1080
  5  - HDV 720p
  6  - Other Hi-Def
  7  - Multimedia
  8  - HDV 1080i
  9  - HD 720
  100  - Music
  101  - Sound effect
"ar" is the aspect ratio
  1  - 4:3
  2  - 16:9 anamorphic
  3  - 16:9 letterboxed
  4  - Unknown
  5  - Other
  6  - 16:9 native
"ox" is the original horizontal resolution of the clip (16 for sound)
"oy" is the original vertical resolution of the clip (9 for sound)
"n" is the name of the clip
"dur" is the duration in ms
"kw" is the plain text keywords
	"id" : 79495,
	"vs" : 2,
	"ar" : 1,
	"ox" : 720,
	"oy" : 480,
	// below by setting "col" bitmask
	"n" : "Flower Pot Dog",
	"dur" : 8300,
	"kw" : "dog costume funny parade flowers pets contest"
Again, see https://www.pond5.com/index.php?page=api_ref_doc for more information about the commands.