Freelancer.com Affiliate API 1.0 documentation

  1. Freelancer.com Affiliate API documentation
    1. What can be done with the Freelancer.com Affiliate API?
    2. Web Widgets
    3. Protocols and formats
    4. Hierarchy of API calls
    5. Resource URI
    6. Common parameters
    7. Limitations on use of API
    8. Output format
      1. Error format
      2. Standard value formats
      3. Custom value formats
    9. API calls
      1. Project/Properties
      2. Project/Search
        1. Project order criteria
      3. User/Properties
      4. Feedback/Search
        1. Feedback order criteria
    10. How to make a web widget and earn bonuses ?
      1. Step 1. Select API call
      2. Step 2. Display results
      3. Step 3. Test
      4. What else can I do about the widget?

What can be done with Freelancer.com Affiliate API?

The API lets users access public information on Freelancer.com programmatically. Such information has to be used in accordance with the Freelancer.com and Affiliate Program Terms of Service. Allowed uses include displaying open public projects or information from user profiles on affiliate websites with appropriate links to Freelancer.com projects or profiles. This information will be useful for all Freelancer.com members. Users who are experienced in programming will be able to create their own widgets with a large degree of flexibility (see API calls). Less experienced users can simply paste the code given in the examples on their web page to enjoy the benefits of our web widgets.

Web Widgets

The API can be used to develop web widgets. A web widget is a portable chunk of code that can be installed and executed within any separate HTML-based web page by an end user without requiring additional compilation.

We host a number of sample widgets. Such widgets may be easily customized and used by clients on their websites.

We encourage users to develop widgets using the API. The easiest way to syndicate information from Freelancer.com to a website is to take the request information in JSON format using the API and output it using Javascript directly onto a website. Tell us about your projects via our support desk, and after review we will host them for you on our servers!

Samples of standard widgets:

  • User profile with "Hire me" link
  • Random feedback about a user with "Hire me" link
  • Random or latest open projects block

Protocols and formats

API is based on HTTP protocol.

A RESTful architecture is used.

Formats of result returned by API: XML, JSON

Hierarchy of API calls

See a more detailed explanation and code examples here

  • User
    • Properties
  • Project
    • Properties
    • Search
      • By expertise
      • By keyword
      • By owner
      • By winner
      • Featured
      • Trial
      • For gold members only
      • Nonpublic
      • By budget
      • By bidding time left
      • Order by: random, start time
  • Feedback
    • Search
      • By receiver and type and status
      • By project
      • Order by: random, time

Resource URI

A URI (Uniform Resource Identifier) is formed as

http://api.freelancer.com/RES_TYPE/(RES_CALL[/RES_ID]|RES_ID).FORMAT_EXT[?PARAMS]

where

RES_TYPE
type of objects accessed, such as projects, users, bids, etc
RES_ID
ID of resource, such as ID of project, bid, user, etc
RES_CALL
name of call which is made against the object. If this paramer is not mentioned, it means that default call "Properties" is used.
FORMAT_EXT
extention used to specify format of output: json - to receive JSON, xml - to receive output in XML

For example

http://api.freelancer.com/Project/Properties.json?id=100 is identical to http://api.freelancer.com/Project/100.json
http://api.freelancer.com/Project/Search.xml?jobs[]=PHP&jobs[]=XML&featured=1
http://api.freelancer.com/Feedback/Search.xml?user=providerUsername&project_id=100

Common parameters

The following parameters are available to all calls:

callback
this is name of function into which we will wrap response in JSON format.
apikey
API key, paramater is optional.
aff
username of affiliate. Include this parameter to the widget's code to make all URLs returned by API affiliate-friendly, meaning that every URL will include the affiliate's username. Use this parameter in your applications to refer new users to Freelancer.com and earn bonus from their commissions and fees.
charset
by default all response is in utf-8. Supported charsets: iso-8859-1, utf-8
format
xml, json, rss. This parameter is included in URI
pg
page number. Starts from 0. Default page is 0
count
number of items on a page

Limitations on use of API

We encourage users to use the API in a good manner, save our server resources using caching. To keep our servers available to all of our clients, we introduce limit-rate on API usage. Users can make up to 300 requests per minute. Each user is granted an API key, which should be used with each request user makes. Requests without a personal API key are limitted on IP-basis, meaning that there may be up to 300 requests from 1 IP address within 1 minute.

Get your API key

In case when API calls are made using client javascript scripts, it doesn't make sense to use API key, cause API calls are made from visitor's web browsers with visitor's IP. In such case it's recommended not to use API key.

Output format

Error format

Any API call may end with a error if something goes wrong. In such case instead of normal output, error output is returned in the following format:

  • errors
    • Array of error

Error output in XML: 

<?xml version="1.0" encoding="UTF-8"?>
<errors xmlns="http://api.freelancer.com/schemas/xml-0.1">
	<error>User is not set. Please set ID or username in parameter &apos;user&apos;</error>
</errors>

Standard value formats

UNIXTIME
seconds since the Unix Epoch (January 1 1970 00:00:00 GMT)
RFC 2822 time
date in RFC 2822 compliant format. Sample: Thu, 21 Dec 2000 16:01:07 +0200
Boolean
1 - true, 0 - false.

Custom value formats

State of project - One char which represents current project state. A - active/open project; F - frozen project, C - closed project.

API calls

Project/Properties

Description

Fetches information about a specific project

URL

2 ways to address this call:

http://api.freelancer.com/Project/<ID>.(json|xml) - Using this URL, ID of the project is included in URL directly without parameters
http://api.freelancer.com/Project/Properties.(json|xml) - Using this URL, ID of the project should be specified in parameter id

Parameters

id
ID of project (required)

Returned results

  • project
    • id - ID of the project
    • name - title of the project
    • url - URL of the project
    • start_unixtime - time when project was started in UNIXTIME format
    • start_date - time when the project was started in RFC 2822 format
    • end_unixtime - time when the project bidding period ends in UNIXTIME format
    • end_date - time when the project bidding period ends in RFC 2822 format
    • buyer
      • url - URL of the buyer's profile
      • id - ID of the buyer's username
      • username - username of the buyer
    • state - state of the project
    • short_descr - shortened text of the project's requirements
    • options
      • featured - boolean value. 1 if project is featured, 0 - only normal projects
      • nonpublic - boolean
      • trial - boolean
      • for_gold_members - boolean
      • hidden_bids - boolean
    • budget
      • min - Numeric double value or empty (false) if no minimum is specified
      • max - Numeric double value or empty (false) if no maximum is specified
    • jobs
      • Array of jobs
    • bid_stats
      • count - number of bids or empty (false) if bid statistics is not available
      • avg - average bid amount or empty (false) if bid statistics is not available

Samples

API Call: http://api.freelancer.com/Project/100000.xml

XML output: 

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://api.freelancer.com/schemas/xml-0.1">
	<id>100000</id>
	<name>creation of Requirements Document for web application (database driven)</name>
	<url>http://www.freelancer.com/projects/PHP-ASP/creation-Requirements-Document-for-web.html</url>
	<start_unixtime>1161563004</start_unixtime>
	<start_date>Sun, 22 Oct 2006 20:23:24 -0400</start_date>
	<end_unixtime>1163726604</end_unixtime>
	<end_date>Thu, 16 Nov 2006 20:23:24 -0500</end_date>
	<buyer>
	    <url>http://www.freelancer.com/users/285543.html</url>
	    <id>285543</id>
    	    <username>rougemarshal</username>
	</buyer>
	<state>C</state>
	<short_descr>We need a wise and experienced developer, well versed and extensive experience with MySQL (or other) and web application languages (e.g...</short_descr>
	<options>
	    <featured>0</featured>
	    <nonpublic>0</nonpublic>
	    <trial>0</trial>
	    <for_gold_members>0</for_gold_members>
	    <hidden_bids>1</hidden_bids>
	</options>
	<budget>
	    <min>100</min>
	    <max>300</max>
	</budget>
	<jobs>
	    <item>ASP</item>
	    <item>Flash</item>
	    <item>PHP</item>
	    <item>Website Design</item>
	    <item>XML</item>
	</jobs>
	<bid_stats>
	    <count>5</count>
	    <avg />
	</bid_stats>
</project>

API Call: http://api.freelancer.com/Project/100000.json

JSON output: 

{"project":{"id":100000,"name":"creation of Requirements Document for web application (database driven)","url":"http://www.freelancer.com/projects/PHP-ASP/creation-Requirements-Document-for-web.html","start_unixtime":1161563004,"start_date":"Sun, 22 Oct 2006 20:23:24 -0400","end_unixtime":1163726604,"end_date":"Thu, 16 Nov 2006 20:23:24 -0500","buyer":{"url":"http://www.freelancer.com/users/285543.html","id":285543,"username":"rougemarshal"},"state":"C","short_descr":"We need a wise and experienced developer, well versed and extensive experience with MySQL (or other) and web application languages (e.g...","options":{"featured":0,"nonpublic":0,"trial":0,"for_gold_members":0,"hidden_bids":1},"budget":{"min":100,"max":300},"jobs":["ASP","Flash","PHP","Website Design","XML"],"bid_stats":{"count":5,"avg":false}}}

Project/Search

Description

Searches projects by different search parameters

URL

http://api.freelancer.com/Project/Search.(json|xml)

Parameters

keyword
Search keyword (optional)
owner
Username of ID of project owner (optional)
winner
Username of ID of project winner (optional)
jobs[]
Names of job categories from the available list on Freelancer.com (PHP, .NET, AJAX, etc.). This parameter may be repeated more than once (optional)
featured
If 1 - only featured projects, if 0 - only NON-featured projects (optional)
trial
If 1 - only trial projects, if 0 - only NON-trial projects (optional)
for_gold_members
If 1 - only "For gold members" projects, if 0 - only NON "For gold members" projects (optional)
nonpublic
If 1 - only nonpublic projects, if 0 - only public projects (optional)
min_budget
Only projects with budget higher or equal to min_budget (optional)
max_budget
Only projects with budget lower or equal to max_budget (optional)
bidding_ends
Only projects ending sooner than bidding_ends days (optional)
order
How to order projects in the result output. See available project order criteria.
order_dir
Direction of sorting. If the parameter is equal to asc, results are ordered in ascending way, otherwise - descending (desc).

Returned results

  • projects
    • count
    • items
      • Array of item
        • id - ID of a project
        • name - title of the project
        • url - URL of the project
        • start_unixtime - time when the project was started in UNIXTIME format
        • start_date - time when the project was started in RFC 2822 format
        • end_unixtime - time when the project bidding period ends in UNIXTIME format
        • end_date - time when the project bidding period ends in RFC 2822 format
        • buyer
          • url - URL of the buyer's profile
          • id - ID of the buyer's username
          • username - username of the buyer
        • state - state of the project
        • short_descr - shortened text of the project's requirements
        • options
          • featured - boolean value. 1 if project is featured, 0 - normal projects only
          • nonpublic - boolean, 1 or 0 (see featured)
          • trial - boolean, 1 or 0 (see featured)
          • for_gold_members - boolean value. 1 for Gold members, 0 - non-Gold members only
          • hidden_bids - boolean value. 1 with hidden bids, 0 - with visible bids only
        • budget
          • min - Numeric double value or empty (false) if no minimum is specified
          • max - Numeric double value or empty (false) if no maximum is specified
        • jobs
          • Array of jobs
        • bid_stats
          • count - number of bids or empty (false) if bid statistics is not available
          • avg - average bid amount or empty (false) if bid statistics is not available

Samples

API Call: http://api.freelancer.com/Project/Search.xml

XML Output: 

<?xml version="1.0" encoding="UTF-8"?>
<projects xmlns="http://api.freelancer.com/schemas/xml-0.1">
	<count>2</count>
	<items>
		<item>
			<id>419503</id>
			<name>Nonpublic project #419503</name>
			<url>http://www.freelancer.com/projects/419503.html</url>

			<start_unixtime>1239887403</start_unixtime>
			<start_date>Thu, 16 Apr 2009 09:10:03 -0400</start_date>
			<end_unixtime>1240751403</end_unixtime>
			<end_date>Sun, 26 Apr 2009 09:10:03 -0400</end_date>
			<buyer>
				<url>http://www.freelancer.com/users/61233.html</url>

				<id>61233</id>
				<username>dlion</username>
			</buyer>
			<state>A</state>
			<short_descr>The project is Nonpublic. Description can be read only by registered users.</short_descr>
			<options>
				<featured>0</featured>

				<nonpublic>1</nonpublic>
				<trial>0</trial>
				<for_gold_members>0</for_gold_members>
				<hidden_bids>1</hidden_bids>
			</options>
			<budget>
				<min>30</min>

				<max>250</max>
			</budget>
			<jobs />
			<bid_stats>
				<count />
				<avg />
			</bid_stats>
		</item>

		<item>
			<id>419504</id>
			<name>flash template customizatio</name>
			<url>http://www.freelancer.com/projects/Flash/flash-template-customizatio.html</url>
			<start_unixtime>1239887283</start_unixtime>
			<start_date>Thu, 16 Apr 2009 09:08:03 -0400</start_date>

			<end_unixtime>1240232883</end_unixtime>
			<end_date>Mon, 20 Apr 2009 09:08:03 -0400</end_date>
			<buyer>
				<url>http://www.freelancer.com/users/415396.html</url>
				<id>415396</id>
				<username>superior5</username>

			</buyer>
			<state>A</state>
			<short_descr>edit flash templates</short_descr>
			<options>
				<featured>0</featured>
				<nonpublic>0</nonpublic>
				<trial>0</trial>

				<for_gold_members>0</for_gold_members>
				<hidden_bids>1</hidden_bids>
			</options>
			<budget>
				<min>30</min>
				<max>250</max>
			</budget>

			<jobs>
				<item>Flash</item>
			</jobs>
			<bid_stats>
				<count>1</count>
				<avg />
			</bid_stats>
		</item>

	</items>
</projects>

API Call: http://api.freelancer.com/Project/Search.json?jobs[]=AJAX&jobs[]=XML&count=2&nonpublic=0&order=rand

JSON output: 

{"projects":{"count":2,"items":[{"id":405177,"name":"Finish our current CMS","url":"http://www.freelancer.com/projects/PHP-Javascript/Finish-our-current-CMS.html","start_unixtime":1237542785,"start_date":"Fri, 20 Mar 2009 05:53:05 -0400","end_unixtime":1240134785,"end_date":"Sun, 19 Apr 2009 05:53:05 -0400","buyer":{"url":"http://www.freelancer.com/users/861992.html","id":861992,"username":"kbvdesign"},"state":"A","short_descr":"We currently have a very basic CMS, with some bugs in it and we want to improve it and make it look better to use it for multiple websites as well...","options":{"featured":0,"nonpublic":0,"trial":0,"for_gold_members":0,"hidden_bids":0},"budget":{"min":250,"max":750},"jobs":["AJAX","Javascript","PHP"],"bid_stats":{"count":33,"avg":456}},{"id":414696,"name":"friendfeed clone","url":"http://www.freelancer.com/projects/C-C-Java/friendfeed-clone.html","start_unixtime":1239096065,"start_date":"Tue, 07 Apr 2009 05:21:05 -0400","end_unixtime":1241688065,"end_date":"Thu, 07 May 2009 05:21:05 -0400","buyer":{"url":"http://www.freelancer.com/users/852388.html","id":852388,"username":"goodmedia"},"state":"A","short_descr":"I need to know how much would a clone of friendfeed.com cost and how long would it take to build?","options":{"featured":0,"nonpublic":0,"trial":0,"for_gold_members":0,"hidden_bids":1},"budget":{"min":250,"max":750},"jobs":[".NET","C/C++","Java","Javascript","XML"],"bid_stats":{"count":25,"avg":false}}]}}

Project order criteria

  • id - order by project ID
  • submitdate - order by date when project was added (default)
  • state - order by state of project. Active/open projects will be listed first, next - frozen and then closed.
  • bid_count - order by number of bids
  • bid_avg - order by average bid
  • bid_enddate - order by bidding end time
  • buyer - order by buyer's username
  • budget - order by budget
  • relevance - order by relevance of search by keyword. This criterion should be used with the parameter keyword
  • rand - order randomly

User/Properties

Description

Fetches information about a specific user

URL

2 ways to address this call:

http://api.freelancer.com/User/<ID>.(json|xml) - Using this URL ID of user is included in URL directly without parameters
http://api.freelancer.com/User/Properties.(json|xml) - Using this URL username or ID of user has to be specified in parameter id

Parameters

id
ID or username of user (required)

Returned results

  • profile
    • url - URL of user profile
    • id - ID of user
    • username
    • logo_url - URL of logo or empty (false)
    • reg_unixtime - time when the user was registered in UNIXTIME format
    • reg_date - time when the user was registered in RFC 2822 format
    • company - company name or false if company is not specified
    • gold - 1 if the user is a gold member currently, 0 - a non-Gold member
    • address
      • country - User's country
      • city - User's city
    • hourlyrate - Hourly rate in USD
    • rating
      • avg - average value of user overral rating, double value from 1 to 10 (i.e. up to 2 digits after the decimal point). false - if user hasn't got any rating yet
      • count - number of feedbacks received by user
    • provider_rating
      • avg - average value of provider rating, double value from 1 to 10. false - if user hasn't got any rating yet
      • count - number of provider feedbacks received by user
    • buyer_rating
      • avg - average value of buyer rating, double value from 1 to 10. false - if user hasn't got any rating yet
      • count - number of buyer feedbacks received by user
    • jobs
      • array of jobs

Samples

API Call: http://api.freelancer.com/User/Properties.xml?id=Freelancer.com

XML output: 

<?xml version="1.0" encoding="UTF-8"?>
<profile xmlns="http://api.freelancer.com/schemas/xml-0.1">
	<url>http://www.freelancer.com/users/49412.html</url>
	<id>49412</id>
	<username>Freelancer.com</username>
	<logo_url />
	<reg_unixtime>1099476682</reg_unixtime>
	<reg_date>Wed, 03 Nov 2004 05:11:22 -0500</reg_date>

	<company>Plendo Sweden AB</company>
	<gold>0</gold>
	<address>
		<country />
		<city />
	</address>
	<hourlyrate>20</hourlyrate>

	<rating>
		<avg />
		<count>0</count>
	</rating>
	<provider_rating>
		<avg />
		<count>0</count>
	</provider_rating>

	<buyer_rating>
		<avg />
		<count>0</count>
	</buyer_rating>
	<jobs>
		<item>Market Research</item>
		<item>Project Management</item>

		<item>Web Promotion</item>
		<item>Website Design</item>
	</jobs>
</profile>

API Call: http://api.freelancer.com/User/49412.json

JSON output: 

{"profile":{"url":"http://www.freelancer.com/users/49412.html","id":49412,"username":"Freelancer.com","logo_url":false,"reg_unixtime":1099476682,"reg_date":"Wed, 03 Nov 2004 05:11:22 -0500","company":"Plendo Sweden AB","gold":0,"address":{"country":null,"city":null},"hourlyrate":20,"rating":{"avg":false,"count":0},"provider_rating":{"avg":false,"count":0},"buyer_rating":{"avg":false,"count":0},"jobs":["Market Research","Project Management","Web Promotion","Website Design"]}}

Feedback/Search

Description

Searches feedbacks by different search parameters

URL

http://api.freelancer.com/Feedback/Search.(json|xml)

Parameters

user
ID or username of a feedback receiver (required)
project_id
ID of project for which the feedback was made (optional)
type
Type of the feedback. S - service provider's (seller's) feedbacks, B - buyer's feedbacks. By default provider's feedbacks are returned (optional)
positive
if positive equals to 1, only feedbacks with rating higher than average will be returned (optional)
order
How to order feedbacks in result output. See available feedback order criteria.
order_dir
Direction of sorting. If the parameter is equal to asc, results are ordered in ascending way, otherwise - descending ('desc').

Returned results

  • feedbacks
    • count
    • items
      • Array of item
        • project
          • id - ID of a project
          • name - title of a project
          • url - URL of a project
        • from_user
          • url - URL of a user's profile
          • id - ID of a user, who left a feedback
          • username - user, who left a feedback
        • active_unixtime - time when feedback was published in UNIXTIME format
        • active_date - time when feedback was published in RFC 2822 format
        • review_type - S - provider's (seller's) feedback, B - buyer's feedback.
        • rating - value of rating from 1 to 10.
        • descr - text of a feedback
        • comment - comment on a feedback left by a feedback receiver
        • bid - provider's offer and price
          • amount - price for doing the project from a project winner bid
          • period - delivery of project in days according to the winning bid
    • user
      • url - URL of user profile
      • id - ID of a user who received feedbacks
      • username - username of feedbacks receiver
    • url - URL of feedback page

Samples

API Call: http://api.freelancer.com/Feedback/Search.xml?user=pinky&count=2&pg=11

XML Output: 

<?xml version="1.0" encoding="UTF-8"?>
<feedbacks xmlns="http://api.freelancer.com/schemas/xml-0.1">
	<count>2</count>
	<items>
		<item>
			<project>
				<id>382695</id>
				<name>Logo with FLASH for Pinly or Best Graphics Artist</name>

				<url>http://www.freelancer.com/projects/Flash-Graphic-Design/Logo-with-FLASH-for-Pinly.html</url>
			</project>
			<from_user>
				<url>http://www.freelancer.com/users/598312.html</url>
				<id>598312</id>
				<username>DoNotTryToConMe</username>
			</from_user>

			<active_unixtime>1235071550</active_unixtime>
			<active_date>2009-02-19 14:25:50</active_date>
			<review_type>S</review_type>
			<rating>10</rating>
			<descr>10+++ As always, this lady did an outstanding job at creating a masterpiece.  Ahe is great to work with and will keep trying to satisfy the customer until e=we are completely happy.  Kudos to Pinky!!!</descr>
			<comment />

			<bid>
				<amount />
				<period />
			</bid>
		</item>
		<item>
			<project>
				<id>387353</id>

				<name>PINKY 36</name>
				<url>http://www.freelancer.com/projects/Flash-Banner-Design/PINKY.387353.html</url>
			</project>
			<from_user>
				<url>http://www.freelancer.com/users/384876.html</url>
				<id>384876</id>
				<username>rajivkanani</username>

			</from_user>
			<active_unixtime>1234974309</active_unixtime>
			<active_date>2009-02-18 11:25:09</active_date>
			<review_type>S</review_type>
			<rating>10</rating>
			<descr>10/10. Pinky&amp;acute;s work is excellent, as always !</descr>

			<comment />
			<bid>
				<amount>60</amount>
				<period>1</period>
			</bid>
		</item>
	</items>
	<user>

		<url>http://www.freelancer.com/users/15003.html</url>
		<id>15003</id>
		<username>pinky</username>
	</user>
	<url>http://www.freelancer.com/users/feedback_15003.html</url>
</feedbacks>

API Call: http://api.freelancer.com/Feedback/Search.json?user=pinky&project_id=413376

JSON output: 

{"feedbacks":{"count":1,"items":[{"project":{"id":413376,"name":"Logo modifications","url":"http://www.freelancer.com/projects/Website-Design-Graphic-Design/Logo-modifications.html"},"from_user":{"url":"http://www.freelancer.com/users/377973.html","id":377973,"username":"bgallagher"},"active_unixtime":1239777281,"active_date":"2009-04-15 02:34:41","review_type":"S","rating":10,"descr":"Great freelancer.  Easy to work with.  Fast response.  Beautiful artwork.  Highly Recommended.","comment":null,"bid":{"amount":75,"period":5}}],"user":{"url":"http://www.freelancer.com/users/15003.html","id":15003,"username":"pinky"},"url":"http://www.freelancer.com/users/feedback_15003.html"}}

Feedback order criteria

  • active_date - order by date when feedback was activated (default)
  • rand - order randomly

How to make a web widget and earn bonuses ?

We will show how to create a widget which displays 1 latest project related to iPhone application development in a few simple steps. Every user who signs up using such widget will be added to the list of referred users and you will earn bonus from each commission paid by referred user. Our widget will be written in Javascript and will fetch results from Freelancer.com in JSON format.

Step 1. Select API call

First lets decide which API call this widget will execute. Base URL of API call is http://api.freelancer.com/Project/Search.json Using this call without parameters will return us a long list of recently posted open projects. As we need only 1 project which is related to iPhone, let's add 2 parameters count=1 and keyword=iphone and grab this project randomly. So our API call will look like: http://api.freelancer.com/Project/Search.json?keyword=iphone&count=1&order=rand

Next, tell the script that you want to participate in affiliate program by adding parameter aff=MyUsername (replace MyUsername with your username), like

http://api.freelancer.com/Project/Search.json?keyword=iphone&count=1&order=rand&aff=MyUsername

This call will produce output similar to: 

{"projects":{"count":1,"items":[{"id":410154,"name":"Simple Iphone game application","url":"http://www.freelancer.com/affiliates/ref.php?u=myusername&l=http%3A%2F%2Fwww.freelancer.com%2Fprojects%2FPHP-C-C%2FSimple-Iphone-game-application.html","start_unixtime":1238376447,"start_date":"Sun, 29 Mar 2009 21:27:27 -0400","end_unixtime":1240968447,"end_date":"Tue, 28 Apr 2009 21:27:27 -0400","buyer":{"url":"http://www.freelancer.com/affiliates/ref.php?u=myusername&l=http%3A%2F%2Fwww.freelancer.com%2Fusers%2F1022666.html","id":1022666,"username":"nnnapps"},"state":"A","short_descr":"I need someone that can copy an online game application into Iphone SDK format. It is very simple and will not require much time...","options":{"featured":0,"nonpublic":0,"trial":1,"for_gold_members":0,"hidden_bids":0},"budget":{"min":750,"max":1500},"jobs":["C/C++","Handheld / PDA","Java","PHP"],"bid_stats":{"count":15,"avg":1082}}]}}

Step 2. Display results

Let's create a function named display_Freelancer.com_project which will display results received from Freelancer.com Affiliate API. This function receives one parameter json - tree of Javascript objects in JSON format. 

function display_Freelancer.com_project(json) {	
	// let's check if received at least 1 project
	if (json.projects.count>0) {
		var p = json.projects.items[0];
		// format budget
		var budget = ((p.budget.min!='' && p.budget.max!='')?'$'+p.budget.min+' - $'+p.budget.max:'')+
				((p.budget.min!='' && p.budget.max=='')?'from $'+p.budget.min:'')+
				((p.budget.min=='' && p.budget.max!='')?'up to $'+p.budget.max:'');
		// format job categories list
		var jobs = null;			
		for (var j=0;j<p.jobs.length;j++) {
			jobs = ((jobs==null)?'':jobs+', ') + p.jobs[j];
		}
		// format project name
		var projectTitle = p.name + 
				(p.options.featured?' <sup><b style="color:darkblue">Featured</b></sup>':'')+
				(p.options.trial?' <sup><b style="color:gray">Trial</b></sup>':'')+
				(p.options.nonpublic?' <sup><b style="color:#694E5A">Nonpublic</b></sup>':'')+
				(p.options.urgent?' <sup><b style="color:red">Urgent</b></sup>':'');
		document.write('<h3>'+projectTitle + '</h3>' + 
			'<p>' + p.short_descr + '</p>' + 
			'<p>Jobs: <small>' + jobs + '</small></p>' + 
			'<p>Budget: ' + budget + '</p>' + 
			'<p><a href="'+p.url+'">Bid on this project</a></p>');						
	}
}

Now we need to call this function and pass JSON object to it. This can be done using API parameter callback in the following way:

http://api.freelancer.com/Project/Search.json?keyword=iphone&count=1&order=rand&aff=MyUsername&callback=display_Freelancer.com_project

This call will produce the following output: 

display_Freelancer.com_project({"projects":{"count":1,"items":[{"id":401230,"name":"iPhone components","url":"http://www.freelancer.com/affiliates/ref.php?u=myusername&l=http%3A%2F%2Fwww.freelancer.com%2Fprojects%2FC-C%2FiPhone-components.html","start_unixtime":1236936875,"start_date":"Fri, 13 Mar 2009 05:34:35 -0400","end_unixtime":1240392875,"end_date":"Wed, 22 Apr 2009 05:34:35 -0400","buyer":{"url":"http://www.freelancer.com/affiliates/ref.php?u=myusername&l=http%3A%2F%2Fwww.freelancer.com%2Fusers%2F232074.html","id":232074,"username":"ahmedaj"},"state":"A","short_descr":"few iPhone application required, and to make things systemic, we would like to give tasks as module,...","options":{"featured":0,"nonpublic":0,"trial":0,"for_gold_members":0,"hidden_bids":1},"budget":{"min":30,"max":250},"jobs":["C/C++"],"bid_stats":{"count":3,"avg":false}}]}})

Step 3. Test

The only thing left is to put everything together and test it. 

<script language="javascript">
<!--
function display_Freelancer.com_project(json) {	
	// let's check if received at least 1 project
	if (json.projects.count>0) {
		var p = json.projects.items[0];
		// format budget
		var budget = ((p.budget.min!='' && p.budget.max!='')?'$'+p.budget.min+' - $'+p.budget.max:'')+
				((p.budget.min!='' && p.budget.max=='')?'from $'+p.budget.min:'')+
				((p.budget.min=='' && p.budget.max!='')?'up to $'+p.budget.max:'');
		// format job categories list
		var jobs = null;			
		for (var j=0;j<p.jobs.length;j++) {
			jobs = ((jobs==null)?'':jobs+', ') + p.jobs[j];
		}
		// format project name
		var projectTitle = p.name + 
				(p.options.featured?' <sup><b style="color:darkblue">Featured</b></sup>':'')+
				(p.options.trial?' <sup><b style="color:gray">Trial</b></sup>':'')+
				(p.options.nonpublic?' <sup><b style="color:#694E5A">Nonpublic</b></sup>':'')+
				(p.options.urgent?' <sup><b style="color:red">Urgent</b></sup>':'');
		document.write('<h3>'+projectTitle + '</h3>' + 
			'<p>' + p.short_descr + '</p>' + 
			'<p>Jobs: <small>' + jobs + '</small></p>' + 
			'<p>Budget: ' + budget + '</p>' + 
			'<p><a href="'+p.url+'">Bid on this project</a></p>');						
	}
}
// -->
</script>
<script src="http://api.freelancer.com/Project/Search.json?keyword=iphone&count=1&order=rand&aff=MyUsername&callback=display_Freelancer.com_project" language="javascript"></script>

Now copy and paste this code onto your website or blog.

What else can I do about the widget?

Look and feel of the widget may be customized by CSS styles and HTML markup.

There are quite a lot of ways how this API can be used. Here're only some ideas:

  • Display latest won projects
  • Create a widget with a search field to search projects by keyword and a list of job categories to specify the search results