Docs — Job API

Overview

Job API is a REST service that aggregates job postings from multiple boards in a single request. It wraps python-jobspy and exposes it as a clean JSON API deployable on Vercel.

Supported job boards: indeed, linkedin, naukri, remoteok, arbeitnow, remotive, jobicy.

Want to test the API interactively? Use the Playground — a built-in API client that lets you send requests and inspect responses in real time.

Quick Start

The simplest possible request — search for software engineer jobs on Indeed:

# Example curl "https://j0b-api.vercel.app/api/jobs?search_term=software+engineer&location=New+York&site_name=indeed&results_wanted=10"

import requests

resp = requests.get(
    "https://j0b-api.vercel.app/api/jobs",
    params={
        "search_term":   "software engineer",
        "location":       "New York, NY",
        "site_name":      "indeed,linkedin",
        "results_wanted": 15,
        "hours_old":      72,
    }
)
data = resp.json()
print(f"Found {data['count']} jobs")
for job in data["jobs"]:
    print(job["title"], "@", job["company"])

const params = new URLSearchParams({
  search_term:    "software engineer",
  location:       "New York, NY",
  site_name:      "indeed,linkedin",
  results_wanted: 15,
  hours_old:      72,
});

const res  = await fetch(`/api/jobs?${params}`);
const data = await res.json();

console.log(`Found ${data.count} jobs`);
data.jobs.forEach(j => console.log(j.title, "@", j.company));

Base URL

https://j0b-api.vercel.app

All endpoints are relative to the base URL. In local development the default is http://localhost:8000.

Endpoints

GET /api/jobs Scrape jobs via query string ▼

Pass all parameters as URL query parameters. Ideal for browser fetches and simple integrations.

Parameter	Type	Required	Default	Description
search_term	string	optional	—	Keyword query. Supports `-negative` and `"exact phrase"`.
site_name	string	optional	all	Comma-separated boards: `indeed`, `linkedin`, `naukri`, `remoteok`, `arbeitnow`, `remotive`, `jobicy`.
location	string	optional	—	City, state, country, or any location string.
country_indeed	string	optional	USA	Country filter for Indeed. E.g. `UK`, `Canada`.
results_wanted	integer	optional	15	Number of results per site (max ~1000).
hours_old	integer	optional	—	Only return jobs posted within the last N hours.
job_type	string	optional	—	`fulltime` \| `parttime` \| `internship` \| `contract`
is_remote	boolean	optional	—	Filter for remote listings only.
distance	integer	optional	50	Search radius in miles.
offset	integer	optional	0	Skip the first N results (for pagination).
description_format	string	optional	markdown	`markdown` \| `html`
easy_apply	boolean	optional	—	Return only jobs with in-board quick apply.
linkedin_fetch_description	boolean	optional	false	Fetch full LinkedIn descriptions (significantly slower).
linkedin_company_ids	string	optional	—	Comma-separated LinkedIn company IDs, e.g. `1441,2382`.
enforce_annual_salary	boolean	optional	false	Normalise all salary figures to annual amounts.
output_format	string	optional	json	`json` \| `csv` \| `excel`
proxies	string	optional	—	Comma-separated proxy list `user:pass@host:port`.

POST /api/jobs Scrape jobs via JSON body ▼

Accepts the same parameters as the GET endpoint but as a JSON body. Array fields like site_name and linkedin_company_ids can be passed as real JSON arrays.

curl -X POST "https://j0b-api.vercel.app/api/jobs" \
  -H "Content-Type: application/json" \
  -d '{
    "site_name": ["indeed", "linkedin"],
    "search_term": "data scientist",
    "location": "San Francisco, CA",
    "results_wanted": 20,
    "hours_old": 48,
    "is_remote": true
  }'

GET /api/health Check API status ▼

Returns a simple status object. Useful for uptime monitoring and deployment checks.

// Response
{
  "status": "ok",
  "service": "Job API",
  "version": "2.0.0"
}

Response Schema

All successful job requests return the following top-level structure:

FieldTypeDescription

jobsarrayArray of job posting objects.

countintegerTotal number of jobs returned.

sitesarrayThe job boards that were queried.

queryobjectEcho of the parameters used for the request.

Job Object

FieldTypeDescription

titlestringJob title.

companystringEmployer name.

sitestringSource board, e.g. indeed.

job_urlstringDirect link to the job posting.

locationobject{ city, state, country }

is_remotebooleanWhether the role is remote.

job_typestringfulltime, parttime, contract, or internship.

job_levelstringSeniority level (where available).

date_postedstringISO-8601 date, e.g. 2025-01-15.

salaryobject{ min_amount, max_amount, interval, currency }

descriptionstringFull job description in the requested format.

emailsarrayContact emails found in the posting.

skillsarraySkills extracted from the description.

company_urlstringURL to the company profile page.

company_industrystringIndustry category.

Code Examples

Remote jobs posted in the last 24h

curl "https://j0b-api.vercel.app/api/jobs?search_term=product+manager&is_remote=true&hours_old=24&results_wanted=25&site_name=linkedin,indeed"

jobs = requests.get("https://j0b-api.vercel.app/api/jobs", params={
    "search_term":    "product manager",
    "is_remote":      "true",
    "hours_old":      24,
    "results_wanted": 25,
    "site_name":      "linkedin,indeed",
}).json()["jobs"]

const { jobs } = await fetch("/api/jobs?" + new URLSearchParams({
  search_term:    "product manager",
  is_remote:      "true",
  hours_old:      24,
  results_wanted: 25,
  site_name:      "linkedin,indeed",
})).then(r => r.json());

Filter by specific LinkedIn companies

curl -X POST "https://j0b-api.vercel.app/api/jobs" \
  -H "Content-Type: application/json" \
  -d '{"site_name":["linkedin"],"search_term":"engineer","linkedin_company_ids":[1441,1035],"results_wanted":50}'