️Unofficial Freelancer.com SDK (Go)

Freelancer.com Go SDK

A Go (Golang) SDK for interacting with the Freelancer.com API.

This library provides a simple, typed client for accessing Freelancer.com services like projects, bids, users, currencies, and more.

---

Why I built this SDK?

As a freelancer, I spend a lot of time on the platform. I wanted to build automated tools (like bidding bots and project monitors) to streamline my workflow, but I realized there was no comprehensive Go client available.

I spent a significant amount of time hand-coding these service wrappers to handle the platform's API nuances. This project is built out of necessity to give Go developers the same power that Python developers have on the platform.

Features

• Authentication: Easy authentication using API Key
• Endpoints: Covers major Freelancer.com endpoints (Users, Projects, Common)
• Design: Clean, idiomatic Go design
• Context Support: All methods support context.Context for timeouts and cancellation.
• License: MIT Licensed — free to use and modify

---

Installation

go get github.com/cushydigit/freelancer-go-sdk

Usage

Authentication

You will need an OAuth2 access token from Freelancer.com. You can generate one in the Freelancer Developer Portal.

Quick Examples

fetch active projects

import (
 "log"
 "github.com/cushydigit/go-freelancer-sdk/freelancer"
)
func QuickExample() {
// create client with access token
 client = freelancer.NewClient(apiAccessToken)
 opts := freelancer.SearchActiveProjectsOptions{
  FullDescription: freelancer.Bool(true),
  Limit:           freelancer.Int(10),
  Offset:          freelancer.Int(5),
  Query:           freelancer.String("golang"),
 }

 res, err := client.Services.Projects.SearchActive(context.Background(), &opts)
 // set parameters
 if err != nil {
  log.Printf("error: %v", err)
  return
 }
 for index, p := range res.Result.Projects {
  log.Println(index, p)
 }

fetch timezones

func ListTimezones() {
res, err := client.Services.Common.ListTimezones(context.Background(), nil)
 if err != nil {
  log.Printf("error: %v", err)
  return
 }
 for index, t := range res.Result.Timezones {
  log.Println(index, t)
 }
}

fetch countries

func ListCountries() {
 res, err := client.Services.Common.ListCountries(context.Background(), nil)
 if err != nil {
  log.Printf("error: %v", err)
  return
 }
 for index, c := range res.Result.Countries {
  fmt.Println(index, c)
 }
}

fetch budgets

func ListBudgets() {
 res, err := client.Services.Projects.Extras.Budgets.List(context.Background(), nil)
 if err != nil {
  log.Printf("error: %v", err)
  return
 }
 for index, b := range res.Result.Budgets {
  fmt.Println(index, b)
 }
}

fetch categories

func ListCategories() {
 res, err := client.Services.Projects.Extras.Categories.List(context.Background(), nil)
 if err != nil {
  log.Printf("error: %v", err)
  return
 }
 for index, c := range res.Result.Categories {
  fmt.Println(index, c)
 }
}

Project Structure

This SDK follows a modular service design. All core logic is located in freelancer.

• client.go: It holds core logic
• types.go: Shared data structures
• responses: The wrappers for API replies
• enums.go: Custom types and constants for statuses, roles, and types
• services.go: The entry point for all services.
• service_*.go: Each file encapsulates logic for a specific API domain

Documentation

Full documentation is available at pkg.go.dev.

For details on the underlying API endpoints and parameters, refer to the official Freelancer.com API Documentation.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development

We use a Makefile to automate common tasks:

make test    # Run all unit tests
make build   # Compile the project

Roadmap

Current version covers Projects, Users, and Common services.

Stability & Quality

• Static Analysis:
• Unit Testing: (32% coverage)
• Use Case:

Upcoming Features

• Messaging: Threads and direct message handling.
• Contests: Browsing and participating in contests.

Changelog

For a detailed list of changes, please see the CHANGELOG.md.

Disclaimer

This is an unofficial library and is not affiliated with, endorsed by, or associated with Freelancer.com. Please ensure you comply with the Freelancer API Terms and Conditions when using this software.

Contact

Feel free to reach out if you have question or suggestions:

• 📧 sh.rahimi.dev@gmail.com
• 💼 LinkedIn
• 🧑‍💻 Freelancer
• 🕊️ X