jobdata API API Documentation

Get started with our simple jobdata API API and fill your jobboard with live jobs in minutes.

OpenAPI Schema + Redoc UI

You can find the schemas documentation in OpenAPI/Swagger format here and basic interactive Redoc version here.

To get an overview of all relevant job search/filter parameters see the examples below for the /api/jobs/ endpoint.

API Examples For /api/jobs/ (Search) Endpoint

Introduction

This endpoint provides access to all job listings in our database under our domain jobdataapi.com. It allows you to retrieve job listings based on various filters and search parameters such as title, location, type, company name, remote availability and more.

To access this endpoint without rate limits, you need to include the Authorization header with the value Api-Key YOUR_API_KEY, where YOUR_API_KEY should be replaced with your actual API key. For quick testing you can also add your API key via the api_key GET parameter to every request.

You can generate an API key from your dashboard if you're a subscribed customer. If you haven't subscribed yet please check our pricing page and hit Subscribe now as it'll make your life as a job board owner so much easier :)

Endpoint Details

Endpoint: /api/jobs/
Method: GET
Authentication Header: Authorization: Api-Key YOUR_API_KEY

The endpoint returns a JSON response with all job post objects ordered by their published date (newest first).

Request Parameters

The /api/jobs/ endpoint supports the following search parameters:

title (optional): Filters job listings based on the job title keywords.
location (optional): Filters job listings based on the job location keywords.
type_id (optional): Filters job listings based on the job type (see /api/jobtypes/ Endpoint).
experience_level (optional): Filters listings based on the min. experience level a job requires.
company_name (optional): Filters job listings based on the company name.
has_remote (optional): Filter jobs by remote availability. Valid values are true or false.
region_id (optional): Filter jobs by region id (see /api/jobregions/ Endpoint).
country_code (optional): Filter jobs by country code (see /api/jobcountries/ Endpoint).
city_name (optional): Filter jobs by city name or city asciiname (see /api/jobcities/ Endpoint).

Note that all text-based parameters are case-insensitive, so for example a value for the city_name can be Berlin as well as berlin. You can find the interactive Redoc version of this endpoint here.

Example Usage

cURL

curl -X GET \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  "https://jobdataapi.com/api/jobs/?title=engineer&location=san+francisco&type_id=1&company_name=example+inc&has_remote=true"

Python

import requests

url = "https://jobdataapi.com/api/jobs/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}
params = {
    "title": "engineer",
    "location": "san francisco",
    "type_id": "1",
    "company_name": "example inc",
    "has_remote": "true"
}

response = requests.get(url, headers=headers, params=params)
data = response.json()
# Process the data as needed

PHP

<?php

$url = "https://jobdataapi.com/api/jobs/";
$headers = [
    "Authorization: Api-Key YOUR_API_KEY"
];
$params = [
    "title" => "engineer",
    "location" => "san francisco",
    "type_id" => "1",
    "company_name" => "example inc",
    "has_remote" => "true"
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));

$response = curl_exec($ch);
$data = json_decode($response, true);
// Process the data as needed

curl_close($ch);
?>

JavaScript

const url = "https://jobdataapi.com/api/jobs/";
const headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
};
const params = {
    "title": "engineer",
    "location": "san francisco",
    "type_id": "1",
    "company_name": "example inc",
    "has_remote": "true"
};

fetch(url + "?" + new URLSearchParams(params), {
    headers: headers
})
.then(response => response.json())
.then(data => {
    // Process the data as needed
})
.catch(error => {
    // Handle any errors
});

Example Parameter Details

Let's explore the different parameters and their usage in detail:

title (optional): This parameter allows you to filter job listings based on the job title. For example, if you set title=engineer, the API will return job listings with "engineer" in their title.
location (optional): You can use this parameter to filter job listings based on the job location. Specify the desired location, such as location=san+francisco, to retrieve job listings available in San Francisco.
type_id (optional): Use this parameter to filter job listings based on the job type. For instance, setting type_id=1 will return full-time job listings.
company_name (optional): This parameter allows you to filter job listings based on the company name. Specify the desired company name, such as company_name=example+inc, to retrieve job listings from Example Inc.
has_remote (optional): Use this parameter to filter job listings based on remote availability. Setting has_remote=true will return job listings that have remote work options available.

Example Response

The response from the /api/jobs/ endpoint will be a JSON object containing the job listings that match the provided search parameters. Each job listing will include details such as title, location, company info, job type, description, etc.

Here's part of an example response for the /api/jobs/ endpoint:

Example call:

curl -X GET -H "Authorization: Api-Key YOUR_API_KEY" https://jobdataapi.com/api/jobs/?has_remote=true&location=san+francisco&title=engineer&type_id=1

{
  "count":1454,
  "next":"https://jobdataapi.com/api/jobs/?has_remote=true&location=san+francisco&page=2&title=engineer&type_id=1",
  "previous":null,
  "results":[{
    "id":1732449,
    "ext_id":"4916732004",
    "company":{
      "id":1447,
      "name":
      "Mercury",
      "logo":"https://jobdataapi.com/media/company/logo/22/01/BankMercury.jpg",
      "website_url":"https://mercury.com/",
      "linkedin_url":"https://www.linkedin.com/company/mercurybank",
      "twitter_handle":"BankMercury",
      "github_url":null
    },
    "title":"Engineering Manager - Financial Leaders",
    "location":"San Francisco, CA, New York, NY, Portland, OR, or Remote within Canada or United States",
    "types":[{"id":1,"name":"Full Time"}],
    ...
    "has_remote":true,
    "published":"2023-06-23T21:31:52Z",
    "description":"Cooperating in large groups comes at a high cost to the individual. It is easiest to see ourselves first through the lens of our culture, and if that culture is one whose social ties are loose and whose resources are controlled and shrewdly rationed by investors seeking return, that lens may leave little room for humanity...",
    "application_url":"https://boards.greenhouse.io/mercury/jobs/4916732004",
    "experience_level":"SE",
    "clearance_required":false,
    "salary_min":null,
    "salary_max":null,
    "salary_currency":null
  }]
}

Feel free to modify the search parameters in the examples provided to fit your requirements and explore the available job listings using the /api/jobs/ endpoint.

API Documentation for `/api/jobtypes/` Endpoint

The /api/jobtypes/ endpoint provides information about different job types available in the system. It returns a JSON response with an array of job type objects. Below is the example response:

{
  "count": 6,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Full Time"
    },
    {
      "id": 2,
      "name": "Part Time"
    },
    {
      "id": 3,
      "name": "Temporary"
    },
    {
      "id": 4,
      "name": "Internship"
    },
    {
      "id": 5,
      "name": "Freelance"
    },
    {
      "id": 6,
      "name": "Contract"
    }
  ]
}

Usage

To retrieve the list of job types, you can make a GET request to the /api/jobtypes/ endpoint. The response will contain an array of job type objects, each having an id and name attribute.

Use the id as a filter value for the /api/jobs/ endpoint to filter job listing results by job type (see /api/jobs/ Endpoint). You can find the interactive Redoc version of this endpoint here.

API Documentation for `/api/jobregions/` Endpoint

The /api/jobregions/ endpoint provides information about different job regions available in the system. It returns a JSON response with an array of job region objects. Below is the example response:

[
    {"id":1,"name":"Africa"},
    {"id":2,"name":"Asia/Pacific"},
    {"id":3,"name":"Europe"},
    {"id":4,"name":"Middle East"},
    {"id":5,"name":"North America"},
    {"id":6,"name":"South America"}
]

Usage

To retrieve the list of job regions, you can make a GET request to the /api/jobregions/ endpoint. The response will contain an array of job region objects, each having an id and name attribute.

Use the id as a filter value for the /api/jobs/ endpoint to filter job listing results by region (see /api/jobs/ Endpoint). You can find the interactive Redoc version of this endpoint here.

API Documentation for `/api/jobcountries/` Endpoint

The /api/jobcountries/ endpoint provides information about all job countries available in the systema, each identified by their unique codes and names. Here's a breakdown of the structure:

code (string): A two-letter abbreviation that uniquely identifies a country. This follows the ISO 3166-1 alpha-2 standard.
name (string): The full name of the country.
region (object): A nested object that provides information about the geographic region to which the country belongs.

id (integer): A unique identifier for the region.
name (string): The name of the region.

It returns a JSON response with an array of job country objects. Below is the example response:

[
    {"code":"AL","name":"Albania","region":{"id":3,"name":"Europe"}},
    {"code":"DZ","name":"Algeria","region":{"id":1,"name":"Africa"}},
    {"code":"AD","name":"Andorra","region":{"id":3,"name":"Europe"}},
    {"code":"AO","name":"Angola","region":{"id":1,"name":"Africa"}},
    {"code":"AG","name":"Antigua and Barbuda","region":{"id":5,"name":"North America"}},
    {"code":"AR","name":"Argentina","region":{"id":6,"name":"South America"}},
    {"code":"AM","name":"Armenia","region":{"id":2,"name":"Asia/Pacific"}},
    {"code":"AW","name":"Aruba","region":{"id":5,"name":"North America"}},
    {"code":"AU","name":"Australia","region":{"id":2,"name":"Asia/Pacific"}},
    {"code":"AT","name":"Austria","region":{"id":3,"name":"Europe"}},
    ...
]

Usage

To retrieve the list of job countries, you can make a GET request to the /api/jobcountries/ endpoint. The response will contain an array of all available job country objects, including their related region info.

Use the code as a filter value for the /api/jobs/ endpoint to filter job listing results by country (see /api/jobs/ Endpoint). You can find the interactive Redoc version of this endpoint here.

API Documentation for `/api/jobcities/` Endpoint

The /api/jobcities/ endpoint provides a exhaustive list of cities available in the system. Here's a breakdown of the structure:

geonameid (Integer): A unique identifier for the city.
asciiname (String): The city's name in ASCII characters. Useful for systems that might have issues with non-ASCII characters.
name (String): The actual name of the city.
country (Object): Contains information about the country where the city is located.
code (String): A short code representing the country.
name (String): The full name of the country.
region (Object): Contains information about the region where the country is located.

id (Integer): A unique identifier for the region.
name (String): The name of the region.

timezone (String): The timezone in which the city is located.

Request Parameters

The /api/jobs/ endpoint supports the following search parameters:

name (optional): Filter cities by their original name.
asciiname (optional): Filter cities by ASCII name (no accents).
country_code (optional): Filter cities by country code (helpful with same city names across different countries).

Note that all text-based parameters are case-insensitive, so for example a value for the asciiname can be Berlin as well as berlin.

This endpoint returns a JSON response with an array of all job city objects ordered by their population size. Below is the example response:

{
    "count":29780,
    "next":"https://jobdataapi.com/api/jobcities/?page=2",
    "previous":null,
    "results":[
        {"geonameid":2332459,"asciiname":"Lagos","name":"Lagos","country":{"code":"NG","name":"Nigeria","region":{"id":1,"name":"Africa"}},"timezone":"Africa/Lagos"},
        {"geonameid":745044,"asciiname":"Istanbul","name":"Istanbul","country":{"code":"TR","name":"Turkey","region":{"id":4,"name":"Middle East"}},"timezone":"Europe/Istanbul"},
        {"geonameid":3435910,"asciiname":"Buenos Aires","name":"Buenos Aires","country":{"code":"AR","name":"Argentina","region":{"id":6,"name":"South America"}},"timezone":"America/Argentina/Buenos_Aires"},
        {"geonameid":1275339,"asciiname":"Mumbai","name":"Mumbai","country":{"code":"IN","name":"India","region":{"id":2,"name":"Asia/Pacific"}},"timezone":"Asia/Kolkata"},
        {"geonameid":3530597,"asciiname":"Mexico City","name":"Mexico City","country":{"code":"MX","name":"Mexico","region":{"id":5,"name":"North America"}},"timezone":"America/Mexico_City"},
        {"geonameid":1174872,"asciiname":"Karachi","name":"Karachi","country":{"code":"PK","name":"Pakistan","region":{"id":2,"name":"Asia/Pacific"}},"timezone":"Asia/Karachi"},
        {"geonameid":1273294,"asciiname":"Delhi","name":"Delhi","country":{"code":"IN","name":"India","region":{"id":2,"name":"Asia/Pacific"}},"timezone":"Asia/Kolkata"},
        {"geonameid":1185241,"asciiname":"Dhaka","name":"Dhaka","country":{"code":"BD","name":"Bangladesh","region":{"id":2,"name":"Asia/Pacific"}},"timezone":"Asia/Dhaka"},
        {"geonameid":1835848,"asciiname":"Seoul","name":"Seoul","country":{"code":"KR","name":"South Korea","region":{"id":2,"name":"Asia/Pacific"}},"timezone":"Asia/Seoul"},
        ...
    ]
}

Usage

To retrieve the list of job cities, you can make a GET request to the /api/jobcities/ endpoint. The response will contain an array of all available job city objects, including their related region info.

The data is paginated, meaning it's broken up into pages for easier consumption. The next and previous fields help navigate through these pages. For example, to get the next set of cities, one would follow the URL provided in the next field.

Use the name or asciiname as a filter value for the /api/jobs/ endpoint to narrow down job listing results to a city (see /api/jobs/ Endpoint). You can find the interactive Redoc version of this endpoint here.