Envato Marketplaces API Introduction for PHP – The Public Set

Hello guys! I’m excited to be writing my debut article for WPKube and today I’m going to talk to you about Envato’s Marketplaces API. Envato is the largest and, in my opinion, possibly one of the most relevant online companies today when it comes to premium WordPress items. With Themeforest.net currently standing at over 4000 premium WordPress themes and Codecanyon.net with over 2500 WordPress plugins, interacting with the marketplaces has become even more important for advertisers in recent times.

Thankfully, Envato allows and encourages this form of interaction via its Marketplaces API. You can check out the official documentation here; http://extras.envato.com/api/. In this article I will cover the public side of this API, including how to use it and provide you with a useful snippet you can customise and drop right into your own projects. At the end I will also share my top 4 data channels in the API, showing you how to use them and what data they will return. Please note that a basic knowledge of using PHP objects will be required. Ready? Let’s begin then.

The difference between the Public and Private APIs

There are two sides to the Envato Marketplaces API. The first is the public set (which I will cover in this article) and the other is the private set. The main difference between them is the fact that the private one requires a valid API key. Check out the other differences below;

• Public:
  • Doesn’t require an API key.
  • Returns general/publically available data such as;
    1. The number of files currently available on a marketplace.
    2. The details of an item (such as price etc).
    3. Public user information (such as number of sales/followers, profile image URL, location etc.)
    4. Search data – this performs a search query on one of the sites and returns the first 50 items.
    5. Popular files on a marketplace.
    6. Featured files on a marketplace.
    7. New files on a marketplace.
• Private:
  • Used to return secure information, such as your balance and earnings.
  • Can be used to;
    1. Return the last 100 items on your statement.
    2. Verify a purchase of your item (this requires your customer’s purchase key).
    3. Download a file you have purchased.

I have only listed a couple of the most useful above, but there are many more. Read the documentation to find out more.

The Code

Let’s dive in head first! The structure for all our code in this tutorial will be very similar; we will use PHP cURL to retrieve JSON data from the API, which we will then convert to a PHP object and use. Below is an example of the basic anatomy of our functions (this particular function will return all the CodeCanyon categories with the number of files in each);

function number_of_files_codecanyon() {
// Open cURL channel
$ch = curl_init();

// Set cURL options
curl_setopt($ch, CURLOPT_URL, "http://marketplace.envato.com/api/edge/number-of-files:codecanyon.json");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Decode returned JSON
$output = json_decode(curl_exec($ch), true);

// Close Channel
curl_close($ch);

// Return output
return $output;
}

When we look at specific uses later you simply need to change the URL on line 6 to suit your needs. To view this data we need to print it to screen (as this is a PHP object be sure to use print_r and not echo). Below is an example of how to print the output from our function as well as the screen output;

echo '<pre>';
print_r( number_of_files_codecanyon() );
echo '</pre>';

Output (don’t worry about the looks for now, we will manipulate the data later on);

stdClass Object
(
[number-of-files] => Array
(
[0] => stdClass Object
(
[category] => JavaScript
[number_of_files] => 1402
[url] => http://codecanyon.net/category/javascript
)

[1] => stdClass Object
(
[category] => PHP Scripts
[number_of_files] => 2096
[url] => http://codecanyon.net/category/php-scripts
)

[2] => stdClass Object
(
[category] => .NET
[number_of_files] => 132
[url] => http://codecanyon.net/category/net
)

. . . etc . . .

… And here is an example of how you could call and use the data from the object.

// Retrieve data from function
$json_data = number_of_files_codecanyon();

// Count number of array items (-1 as the object is zero-based)
$data_count = count($json_data['number-of-files']) -1;
 
// Output as list   
echo '<ul>';

// Echo code for every category
for($i = 0; $i <= $data_count; $i++) {
 // Retrieve and print data
 echo '<li><a href="'.$json_data['number-of-files'][$i]['url'].'">',$json_data['number-of-files'][$i]['category'],'</a> - ',$json_data['number-of-files'][$i]['number_of_files'],'</li>';
}
echo '/<ul>';

This will return the following HTML;

• JavaScript – 1402
• PHP Scripts – 2096
• .NET – 132
• WordPress – 2542
• Plugins – 608
• CSS – 697
• HTML5 – 350
• Mobile – 696
• Apps – 225
• Skins – 98
• Edge Animate Templates – 54

That’s it for the basics! Now let’s have a look at some of the specific uses.

Although I am not going to go through every possible data channel here, all of them are explained in the API Documentation.

My Top 4 Most Useful Data Channels

1. Retrieve Item data; URL: http://marketplace.envato.com/api/edge/item:{ ITEM_ID }.json The ‘ITEM_ID’ parameter accepts an integer. This corresponds to the unique ID given to a product by Envato. This will return the following JSON data;

   Array
   (
   [item] => Array
   (
   [id] => 5850316
   [item] => TCWP – Supercharged Twitter Card Management for WP
   [url] => http://codecanyon.net/item/tcwp-supercharged-twitter-card-management-for-wp/5850316
   [user] => InfinityCode
   [thumbnail] => http://3.s3.envato.com/files/87961812/TCWPLogo.png
   [sales] => 13
   [rating] => 5.0
   [rating_decimal] => 5.00
   [cost] => 18.00
   [uploaded_on] => Mon Oct 14 18:16:01 +1100 2013
   [last_update] => Fri May 02 05:47:29 +1000 2014
   [tags] => cards, customer, embed, integration, meta, outreach, photo, player, product, seo, social, social media, summary, twitter, twitter cards
   [category] => wordpress/social-networking
   [live_preview_url] => http://1.s3.envato.com/files/89907849/TCWPHeader.jpg
   [live_preview_video_url] => http://0.s3.envato.com/files/90359042/TCWPVideoPreview720p.mp4
   )
   
   )
   

2. Retrieve Featured Item (and Free File of the Month); URL: http://marketplace.envato.com/api/edge/features:{ MARKETPLACE_NAME }.json The ‘MARKETPLACE_NAME’ parameter accepts a string. This corresponds to the lowercase name of the marketplace to be queried, eg. ‘codecanyon’, ‘activeden’ etc. This will return the following JSON data;

   Array
   (
   [features] => Array
   (
   [featured_file] => Array
   (
   [id] => 7157644
   [item] => FlatAds - Classified AdsWordPress Theme
   [url] => http://themeforest.net/item/flatads-classified-adswordpress-theme/7157644
   [user] => Themes-Dojo
   [thumbnail] => http://2.s3.envato.com/files/90383318/80x80.jpg
   [sales] => 200
   [rating] => 4.0
   [rating_decimal] => 3.80
   [cost] => 55.00
   [uploaded_on] => Sun Mar 23 15:13:01 +1100 2014
   [last_update] => Sun May 04 23:02:49 +1000 2014
   [tags] => ads, advertising, bbpress, business, classified, classified ads, corporate, database, directory, listing, marketing, portal, responsive, woocommerce, wpml
   [category] => wordpress/corporate/directory-listings
   [live_preview_url] => http://2.s3.envato.com/files/90383319/images/01_preview.__large_preview.jpg
   )
   
   [featured_author] => Array
   (
   [id] => 379972
   [user] => biyanpasau
   [url] => http://themeforest.net/user/biyanpasau
   [thumbnail] => http://2.s3.envato.com/files/63718853/ava.png
   )
   
   [free_file] => Array
   (
   [id] => 4114650
   [item] => Emotion - Responsive HTML5/CSS3 Template
   [url] => http://themeforest.net/item/emotion-responsive-html5css3-template/4114650
   [user] => dan_fisher
   [thumbnail] => http://0.s3.envato.com/files/58994756/thumb.jpg
   [sales] => 101
   [rating] => 5.0
   [rating_decimal] => 5.00
   [cost] => 15.00
   [uploaded_on] => Tue Feb 26 08:23:51 +1100 2013
   [last_update] => Wed Jun 12 21:58:55 +1000 2013
   [tags] => blog, creative, css3, emotion, flexible, green, html5, minimal, modern, multipurpose, perfect, professional, responsive, slider
   [category] => site-templates/creative/portfolio
   [live_preview_url] => http://2.s3.envato.com/files/58994760/preview.__large_preview.jpg
   )
   
   )
   
   )
   

3. Retrieve Popular Items; URL: http://marketplace.envato.com/api/edge/popular:{ MARKETPLACE_NAME }.json The ‘MARKETPLACE_NAME’ parameter accepts a string. This corresponds to the lowercase name of the marketplace to be queried, eg. ‘codecanyon’, ‘activeden’ etc. This will return the following JSON data;

   Array
   (
   [popular] => Array
   (
   [items_last_week] => Array
   (
   [0] => Array
   (
   [id] => 49745
   [item] => Flash Banner Creator and Rotator
   [url] => http://activeden.net/item/flash-banner-creator-and-rotator/49745
   [user] => skyplugins
   [thumbnail] => http://3.s3.envato.com/files/143908.jpg
   [sales] => 4
   [rating] => 4.5
   [rating_decimal] => 4.50
   [cost] => 15.00
   [uploaded_on] => Fri Jul 17 05:17:52 +1000 2009
   [last_update] => Sun May 16 12:49:50 +1000 2010
   [tags] => ads, advertising, banner creator, black, blue, easy to use, flash ad creator, intro, intro builder, orange, red, slideshow, slideshow, xml banner maker, xml banner rotator
   [category] => flash/image-viewers/banner-rotators
   )
   
   . . . & 35 more . . .
   
   [items_last_three_months] => Array
   (
   [0] => Array
   (
   [id] => 6122555
   [item] => Professional Banner Ads 1
   [url] => http://activeden.net/item/professional-banner-ads-1/6122555
   [user] => toosq
   [thumbnail] => http://1.s3.envato.com/files/72736598/Thumbnail.jpg
   [sales] => 27
   [rating] => 5.0
   [rating_decimal] => 4.83
   [cost] => 5.00
   [uploaded_on] => Sat Nov 16 05:22:23 +1100 2013
   [last_update] => Sat Nov 16 05:36:24 +1100 2013
   [tags] => ad, adwords, banner, envato, google, graphic, image, logo, sale
   [category] => flash/animations
   [live_preview_url] => http://1.s3.envato.com/files/72736599/PreviewImage.jpg
   )
   
   . . . & 46 more . . .
   
   [authors_last_month] => Array
   (
   [0] => Array
   (
   [item] => barisintepe
   [sales] => 53
   [url] => http://activeden.net/user/barisintepe
   [image] => http://0.s3.envato.com/files/1312722/my_logo.png
   )
   
   . . . & 18 more . . .
   
   

4. Search Items; URL: http://marketplace.envato.com/api/edge/search:{ SITENAME },{ CATEGORY },{ SEARCH_TERM }.json The ‘SITENAME’ parameter accepts a string. This corresponds to the lowercase name of the marketplace to be queried, eg. ‘codecanyon’, ‘activeden’ etc. The ‘CATEGORY’ parameter accepts a string. This is an optional list of category and sub-categories. The list strings must be separated by %2f (URL escaped /) e.g. music%2fcorporate%2fmotivational The ‘SEARCH_TERM’ parameter accepts a string. This is the search expression (e.g. xml, preloader, dance, sky). The expression parameter may also use basic search logic, such as AND, OR or grouping. For example the following expression will search for ‘theme’ and ‘blue’ or ‘green’: theme|and|(blue|or|green). An expression such as ‘blue|green|yellow’ is equivalent to ‘blue|and|green|and|yellow’. The First and second parameters are optional, third is required. This will return the following JSON data;

   Array
   (
   [search] => Array
   (
   [0] => Array
   (
   [id] => 5150861
   [description] => Positive & Happy
   [url] => http://audiojungle.net/item/positive-happy/5150861
   [type] => music/corporate/motivational
   [sales] => 3
   [rating] => 0.0
   )
   
   . . . & 49 more . . .
   
   

That’s it! I hope you have found this very brief introduction to the Envato API useful and if you have any questions or are unclear about something simply ask me below or tweet me @harribellthomas.