jobdata

Jobs API Endpoint Documentation

Fetching job listings with advanced filters.

Docs Job data
Table of contents

Introduction

The Jobs endpoint is a powerful feature of the jobdata API, designed to offer comprehensive access to job postings from thousands of companies across various industries. This endpoint facilitates the retrieval of job listings with detailed information, including job title, location, company details, job type, and more. It caters to a wide range of users, from job search platforms to HR software, enabling them to access up-to-date job data directly from companies' ATS (Applicant Tracking System) and career platforms.

Endpoint Overview

Endpoint (list): /api/jobs/

Endpoint (single element): /api/jobs/{id}/

Method: GET

Authorization Required: Yes

Description: This endpoint allows users to fetch job listings based on various filters such as company name, job title, location, and more. Each job listing includes comprehensive details about the job, such as the company information, job type, application link, and description. It's designed to provide quality job data for various applications, including job search engines, market analysis, and HR solutions.

Request

To access the Jobs endpoint, include an authorization header with your API key. Here's how to make a request using both curl and Python.

Using curl

curl -X GET "https://jobdataapi.com/api/jobs/?title=Software%20Engineer&location=New%20York" \
     -H "Authorization: Api-Key YOUR_API_KEY"

Using Python

import requests

url = "https://jobdataapi.com/api/jobs/"
params = {"title": "Software Engineer", "location": "New York"}
headers = {"Authorization": "Api-Key YOUR_API_KEY"}
response = requests.get(url, headers=headers, params=params)
print(response.json())

Parameters

The Jobs endpoint supports several parameters for filtering job listings or adding additional fields, enhancing the flexibility and precision of job searches.

  • include_agencies: Includes jobs from recruiting/staffing agencies in the results. Can be true or false - the default is false internally. So when no include_agencies=true is added as a query parameter, job listings from agencies are excluded from all results.
  • company_is_agency: Show listings from either recruiting/staffing agencies (with company_is_agency=true) or only from companies hiring directly with company_is_agency=false (the default is false internally).
  • company_id: Filters jobs by the ID of the company offering the job - requires a valid API key.
  • company_name: Filters jobs by the name of the company offering the job(s).
  • company_website: Filters jobs by a company domain name or its website URL.
  • country_id: Filters jobs by the country ID of the job location (see Job Countries endpoint for more info).
  • country_code: Filters jobs by the country code of the job location (ISO 3166-1 alpha-2 code, see Job Countries endpoint for more info).
  • state_id: Filters jobs by the state ID of the job location (see Job States endpoint for more info).
  • state_code: Filters jobs by the state code of the job location. This usually requires the country_code or country_id parameter to be set as well to avoid results from different states with the same code as it's not a unique identifier (see Job States endpoint for more info).
  • city_id: Filters jobs by the city ID of the job location (see Job Cities endpoint for more info).
  • city_name: Filters jobs by the name of the city where the job is located.
  • description: Filters jobs by keywords or phrases in the job description, see the full-text search documentation page for more details - requires access pro subscription.
  • description_str: When used with value true this adds an additional field description_string to every result set object containing a stripped version of the description string without any html tags and other non-text/informational data (Changelog v4.1).
  • exclude_expired: Excludes expired job listings from the results when set to true - requires access pro subscription.
  • experience_level: Filters jobs by the required experience level (EN for Entry Level, MI for Mid Level, SE for Senior Level and EX for Executive level).
  • has_remote: Filters jobs based on whether they offer remote work options (value can be true or false for filtering either all non-remote or remote/wfh/hybrid listings).
  • language: Filters jobs by the language in which the job post is written (ISO 639 language code, e.g. en, fr, de, etc. - see all available codes on the language stats page).
  • location: Filters jobs by a string within the general location description that comes with a job post, also allows for an |OR| operater (see details below).
  • location_str: When used with value true this adds an additional field location_string to every result set object containing a GeoNames-optimized location string (Changelog v4.3).
  • max_age: Filters jobs by the maximum age (in days, 1 - 999) since they were published.
  • min_salary: Filters jobs by the minimum yearly salary (FTE) offered.
  • published_since: Filters jobs published since a specific date (YYYY-MM-DD).
  • published_until: Filters jobs published until a specific date (YYYY-MM-DD).
  • region_id: Filters jobs by the region ID where the job is located (see Job Regions endpoint for more info).
  • salary_currency: Filters jobs by the currency of the salary offered (see available currency values below).
  • title: Filters jobs by the job title, also allows for an |OR| operater (see details below).
  • type_id: Filters jobs by the job type ID (see Job Types endpoint for more info).
  • min_id: Filters for all jobs that have a job ID equal or larger - requires a valid API key.
  • max_id: Filters for all jobs that have a job ID equal or smaller - requires a valid API key.
  • page: Specifies the page number in the paginated result set - requires a valid API key.
  • page_size: Determines the number of results per page (1 - 5000, default: 200) - requires a valid API key.

Advanced Company Info Parameters

The following company-related query parameters require an access pro subscription:

  • company_founded_after: Filters companies by their founding year, selecting those founded after the specified year.
  • company_founded_before: Filters companies by their founding year, selecting those founded before the specified year.
  • company_founded_in: Filters companies by their exact founding year.
  • company_hq: Filters jobs by the headquarters location of the company offering the job.
  • company_industry_id: Filters jobs by the industry ID of the company offering the job (see Industries endpoint for more info).
  • company_max_size: Filters companies by their maximum size (number of employees).
  • company_min_size: Filters companies by their minimum size (number of employees).
  • company_specialty: Filters jobs by the specialty or focus area of the company.
  • company_type_id: Filters jobs by the type ID of the company offering the job (see Company Types endpoint for more info).

Also see the Companies API Endpoint Documentation for more info on company attributes.

Salary Currency Parameter Values

The list of currently available salary currencies for the /api/jobs/ endpoint in the Jobdata API is as follows:

  • AUD (Australian Dollar)
  • THB (Baht)
  • BRL (Brazilian Real)
  • BGN (Bulgarian Lev)
  • CAD (Canadian Dollar)
  • CLP (Chilean peso)
  • COP (Colombian Peso)
  • CZK (Czech Koruna)
  • DKK (Danish Krone)
  • EUR (Euro)
  • HUF (Forint)
  • HKD (Hong Kong Dollar)
  • INR (Indian Rupee)
  • MXN (Mexican peso)
  • ILS (New Israeli Sheqel)
  • TWD (New Taiwan Dollar)
  • NZD (New Zealand Dollar)
  • NOK (Norwegian Krone)
  • PHP (Philippine Peso)
  • GBP (Pound Sterling)
  • ZAR (Rand)
  • RON (Romanian Leu)
  • IDR (Rupiah)
  • SGD (Singapore Dollar)
  • KRW (South Korean Won)
  • LKR (Sri Lankan Rupee)
  • SEK (Swedish Krona)
  • CHF (Swiss Franc)
  • TRY (Turkish Lira)
  • USD (US Dollar)
  • JPY (Yen)
  • PLN (Zloty)

These currencies provide a broad spectrum for specifying salary ranges in job postings, accommodating the global reach of job listings available through the Jobdata API. Users can specify the salary_currency query parameter to filter job listings based on the desired currency for salary information.

Using the |OR| Operator in Location and Title Queries

The |OR| operator can be used to expand your search criteria on the title and location parameters, allowing you to query for jobs that match any of the specified values. Don't forget to include the "|" (pipe) symbols as in "|OR|" and not "OR" - the latter would be treated as just another title search term (this is different from the "OR" operator for the full-text search in job descriptions).

Examples

To search for jobs in either "New York" or "San Francisco", you would format your query parameter as follows:

location=New+York|OR|San+Francisco

To look for jobs with the title "Software Engineer" or "Product Manager", your query parameter would be:

title=Software+Engineer|OR|Product+Manager

Example Request with Curl

curl -X GET "https://jobdataapi.com/api/jobs/?location=New+York|OR|San+Francisco&title=Software+Engineer|OR|Product+Manager" \
     -H "Authorization: Api-Key YOUR_API_KEY"

Example Request in Python

import requests

url = "https://jobdataapi.com/api/jobs/"
params = {
    "location": "New York|OR|San Francisco",
    "title": "Software Engineer|OR|Product Manager"
}
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())

The |OR| operator is a powerful tool that enhances the flexibility and efficiency of your job searches on the Jobdata API, allowing for more comprehensive and tailored search results.

Response

The response from the Jobs endpoint is a JSON object that includes a count of total job listings matching the query and an array of job details, basic company info for each job and related geolocation information.

Top-Level Response Structure

  • count: An integer indicating the total number of job listings available that match the query.
  • next: A URI to the next page of results, if available; otherwise, null. This helps in navigating through paginated data.
  • previous: A URI to the previous page of results, if available; otherwise, null. It allows users to navigate back to the previous set of results.
  • results: An array of job listings, where each job listing is a detailed object with various attributes.

Job Listing Structure (results array items)

Each item in the results array represents a job listing with the following properties:

  • id: The unique identifier for the job listing (read-only).
  • ext_id: An optional external identifier for the job listing.
  • company: An object containing detailed information about the company posting the job. This includes the company's name, logo, website URL, and social media links, providing a comprehensive view of the employer.
  • title: The title of the job listing.
  • location: The location where the job is based.
  • types: An array of job types (e.g., full-time, part-time) associated with the job listing.
  • cities: An array of cities related to the job location, providing a detailed geographical context.
  • countries: An array of countries associated with the job location, offering a broader geographical scope.
  • regions: An array of regions associated with the job location, further refining the geographical details.
  • has_remote: A boolean indicating whether the job offers a remote working option, which is crucial for applicants looking for flexible working conditions.
  • published: The publication date and time of the job listing.
  • description: A detailed description of the job, including responsibilities, qualifications, and other important details.
  • description_string: A cleaned up and stripped version of the job description (only shown when parameter description_str=true is added to a query).
  • experience_level: Indicates the required experience level for applicants (e.g., entry-level, senior).
  • application_url: A URL where applicants can apply for the job directly, ensuring a seamless application process.
  • language: The language code for the job listing, indicating the required language proficiency.
  • salary_min and salary_max: Optional fields indicating the minimum and maximum yearly salary (FTE) for the job, providing transparency about compensation.
  • salary_currency: The currency of the salary, which helps applicants understand the value of the compensation in their local context (see currency values).

Example Response

{
  "count": 2,
  "next": "https://jobdataapi.com/api/jobs/?page=2",
  "previous": null,
  "results": [
    {
      "id": 12345,
      "company": {
        "name": "Tech Innovations Inc.",
        "logo": "https://example.com/logo.png",
        "website_url": "https://techinnovations.com",
        "linkedin_url": "https://linkedin.com/company/tech-innovations-inc",
        ...
      },
      "title": "Senior Software Engineer",
      "location": "Remote",
      "has_remote": true,
      "published": "2024-02-01",
      "description": "We are looking for a Senior Software Engineer...",
      "experience_level": "SE",
      "application_url": "https://techinnovations.com/careers/12345",
      "salary_min": "100000",
      "salary_max": "150000",
      "salary_currency": "USD",
      ...
    },
    // Additional job listings...
  ]
}

Use Cases

  • Job Search Platforms: Easily integrate the latest job listings into job search platforms, providing users with up-to-date information.
  • HR Software: Use the API to assist businesses in broadcasting their job openings and managing applications.
  • Market Analysis: Analysts can leverage the job data for insights into hiring trends, popular job locations, and salary benchmarks.
  • Personalized Job Alerts: Develop applications that send personalized job alerts to users based on their preferences and qualifications.

Notes

  • The has_remote parameter is useful for platforms focusing on remote work opportunities.
  • The description_str parameter is particularly useful for saving cleaning steps in your data pipeline for further processing of job descriptions (e.g. text analysis, NLP, model training, etc.).
  • Use the pagination parameters (page and page_size) to manage the volume of data and navigate through large sets of job listings efficiently.
  • The Authorization header should be included in every request to authenticate your access.
  • The min_id and max_id parameters allow for fetching all jobs from a certain ID range/offset. This can be used to retrieve job posts in the sequence they where added in the database and not by date published for example.

By leveraging the Jobs endpoint, users can tap into a vast database of job listings, enabling a wide range of applications from job discovery to market research, all backed by accurate and timely data directly from employers.

Related Docs

Job Regions API Endpoint Documentation
View documentation
Job Types API Endpoint Documentation
View documentation
Job Cities API Endpoint Documentation
View documentation
Jobs Expired API Endpoint Documentation
View documentation
CSV File Downloads Documentation
View documentation
Job Countries API Endpoint Documentation
View documentation
Full-Text Search on Job Descriptions
View documentation
Job States API Endpoint Documentation
View documentation