FREELANCeR Local jobs API Tutorial

Coding time: ~30 minutes

To get familiar with Freelancer’s Local Jobs API, let's use the API to build a sample Hackathon project called “MobFlash”. You can find the template for MobFlash in this repository

MobFlash.png

Sample App: MobFlash

MobFlash is an app that would help make your next Valentine’s Day surprise way more memorable! In just a single click, you can get connected to multiple Flash Mob dance crews, expert videographers and sound engineers, top florists, and event organizers in your town -- all to make your romantic day extra special.  

freelancer powered.png

 

What we need for this tutorial:

  • cURL command
  • Python 3
  • Git

 

FREELANCER SANDbox

It’s going to be quite difficult to test out the API in production, since we need to undergo verification for our user accounts, set up payment methods, and get your project validated before we can test out our app. But don’t fret! That’s the reason why we have the Freelancer Sandbox [https://www.freelancer-sandbox.com].

The Freelancer Sandbox is a production-like system, and is intended for testing and integration purposes. You are able to register multiple accounts within the sandbox to simulate both the freelancer and employer side of our marketplace. 


Let’s signup an employer account in https://www.freelancer-sandbox.com/signup. Don’t forget to tick the Hire button for your employer account.

 

Freelancer Sandbox - Developer Control Panel

There are a number of caveats in place within the sandbox environment. For example, we do not currently:

  • send any outbound email from the sandbox;
  • allow deposits or withdrawals within the sandbox;
  • support mobile push notifications;
  • support user password reset.
Freelancer.png

To overcome some of these limitations we have enabled a sandbox specific developer control panel [https://www.freelancer-sandbox.com/developer-user-config]. From this page you are able to set various options for your currently logged in user account. These options include:

  • setting email verification status;
  • setting payment verification status;
  • setting phone verification status;
  • depositing funds into various currency balances;
  • activating any pending projects that have been posted.

Let’s use the developer control panel [https://www.freelancer-sandbox.com/developer-user-config/] to get our email, payment, phone, and secure phone verified.

Below the user configuration section, you probably noticed the balance configuration section, where you can magically deposit funds into various currency balances. Since you’ve made it this far, why not reward yourself with some cash? Don’t forget to tip yourself some extra!

Below the balance configuration section, you’ll have a section where you can activate your projects. We’ll look into this later once we’ve posted a project using the API.

 

Getting your api access token

Next, we need to get an OAuth token which will allow us to make authenticated requests to the API. Usually, you would need to create an application and configure it to redirect to an OAuth endpoint on your application server, but we can generate an OAuth access token for the logged in user. This token will allow us to make authenticated requests as the logged in user.

freelancer-sandbox-develop.png

Head to https://accounts.freelancer-sandbox.com/settings/develop and select Generate Token. With that newly generated token, we’re all set to do our first API request.

 

API REQUEST: "HELLO WORLD"

Our first API request would be done via the cURL command. Let’s use our access token to access a user’s protected resource. Let's run this in your command line to retrieve details of our user in JSON format.

curl -X GET https://www.freelancer-sandbox.com/api/users/0.1/self -H "Freelancer-OAuth-V1: *your-oauth-token-here*"

Alright! We've done our first API call. Now, let's start building our MobFlash app.

We would need to specify the currency of the job we're going to post. Say we're going to use Philippine Peso for this one.  Let's do an API call to list down all the currencies that are available.  

curl -X GET "https://www.freelancer-sandbox.com/api/projects/0.1/currencies"

As an additional note, we don't need our API token for this kind of API call. Here's a snippet of the response.  

...
{"code":"PHP","name":"Philippine Peso","country":"PH","sign":"\u20b1","exchange_rate":0.0197,"id":7,"is_external":false}
...

We can find that the currency ID for the Philippine Peso is 7. Let's keep track of this.

Also, we need to find the skills required for our projects. Here’s our API call:

curl -X GET "https://www.freelancer-sandbox.com/api/projects/0.1/jobs"
Response Snippet:
...{ "category": { "id": 12, "name": "Local Jobs & Services" }, "name": "Event Staffing", "seo_url": "event-staffing", "active_project_count": null, "local": true, "id": 864, "seo_info": null }, { "category": { "id": 3, "name": "Design, Media & Architecture" }, "name": "Photography", "seo_url": "photography", "active_project_count": null, "local": true, "id": 27, "seo_info": null }, ...

This would list us all the skills that we can tag for our job. In the responses, we would probably want Event Staffing (id: 864) and Photography (id: 27) for our MobFlash project.

Just an additional note, for our project to be considered as a Local Jobs project, we would need to tag at least one skill that is under the Local Jobs & Services category.

 

Creating a Project

Now that we're all set, let's perform an API call to find awesome dance crews participating in our flash mob. Let's finally use Python and its request library on this one!

We might need to run this command to install the requests library:

$ pip install requests

 

Here's the source code:

import requests

AUTH_TOKEN = ''
BASE_URL = "https://www.freelancer-sandbox.com"
end_point = "/api/projects/0.1/projects/?compact="

currency_id = 7
title = "Flash Mob participation in Quezon City"
description = "I'll be proposing to my wife in two weeks time. Please, help me plan out the special surprise! Unicorn as a theme."
min_budget = 3000
max_budget = 5000
latitude = 14.6552
longitude = 121.0651
jobs = [{
    "id": 864
}]
city = "Quezon City"
country_name = "Philippines"


def post_local_jobs(title, description, currency_id, min_budget, max_budget, jobs, city, country_name, latitude, longitude):
    header = {
        'content-type': 'application/json',
        'Freelancer-OAuth-V1': AUTH_TOKEN,
    }

    data = {
        "title": title,
        "description": description,
        "currency": {
            "id": currency_id
        },
        "budget": {
            "minimum": min_budget,
            "maximum": max_budget
        },
        "jobs": jobs,
        "location": {
            "city": city,
            "country": {
                "name": country_name
            },
            "latitude": latitude,
            "longitude": longitude
        }
    }

    response = requests.post(BASE_URL + end_point, headers=header, json=data)
    return response

response = post_local_jobs(title, description, currency_id, min_budget, max_budget, jobs, city, country_name, latitude, longitude)
print(response.text)

Don't forget to put your API token in the AUTH_TOKEN variable.

Save and run this Python code. If it works, our program would print a JSON response with a success status. Great! We've just posted a project on behalf of our user.

 

ACTIVATING our projects via the developer-user-config

Flash Mob Participation.png

After posting our project, we would need to wait for it to get activated. Let's head to the developer-user-config and activate our project. Hit the Activate all my pending projects button.

It's posted now.png

Success! We've just posted our project! Next thing we need to do is to integrate the Python code above with the MobFlash app.

Plot twist: We'll leave this part as an exercise. 

 

Exercise: Mobflash integration

Start by pulling the MobFlash project. It's made using the Flask micro-framework. For the installation guide, refer to the repository's README file

Your task now is to complete the post_local_jobs function. Complete the feature where two local jobs project (one for the Flash Mob participants while another one for videographers) would be posted after hitting the Book Now button. 

Booking Sucessful.png

Everything's set up for you, so this shouldn't be that hard. Happy coding!

 

MORE use-cases!

Activate Project.png

You can be extra creative with your Hackathon project! Feel free to mix the Freelancer.com API with tons of available APIs online such as Social APIs, Location APIs (e.g. Google Maps, Yelp), Uber API, SMS APIs, Facial Recognition APIs (Trueface.ai, Clarifai), Sentiment Analysis (Alchemy Text, IBM Watson Tone Analyzer) and more.

Innovation never ends!

 

learning more

Check out the Freelancer API's complete documentation to discover more things you can do with the API.

Software Development Kits (SDKs) are also available for Python and Android Studio for easy integration.