Jobs Expired API Endpoint Documentation

Table of contents

Introduction

The Expired Jobs endpoint is a powerful feature available for access pro subscribers of the jobdata API. It offers access to job listings that have expired, allowing users to track the lifecycle of job postings, understand hiring trends over time, and ensure that their platforms or databases maintain current and relevant job information. This capability is particularly useful for job search platforms, HR software solutions, and market research analysts looking to analyze job market dynamics and the longevity of job postings.

Limitations

Keeping up with the lifespan of millions of jobs at all times is quite resource intense and subject to some inherent limitations given by how many ATS (applicant tracking systems) work. We do our best to provide the most accurate data in time but we cannot guarantee full coverage and accuracy.

At the moment about 80~90% of all jobs expired data is on time and accurate. This also means that at any given moment up to 2 in 10 jobs might not be tracked in a timely fashion (usually with a delay of a few days though).

Additionally we have an internal 180 days rule after which jobs expire automatically in our database. This is also to distinguish real vacancies from those that companies occasionally like to keep published for years or have simply forgotten about.

Endpoint Overview

Endpoint (list): /api/jobsexpired/

Endpoint (single element, via Job ID): /api/jobsexpired/{id}/

Method: GET

Authorization Required: Yes (access pro subscription)

Description: Retrieves a list of job postings that have expired within a specified date range. This endpoint helps in cleaning up outdated job listings from user-facing platforms and provides valuable data for analyzing job market trends.

Request

Making a request to the Expired Jobs endpoint requires an authorization header with a pro access API key. Below are examples of how to make a request using curl and Python.

Using curl

curl -X GET "https://jobdataapi.com/api/jobsexpired/?country_code=US&expired_since=2023-01-01&expired_until=2023-01-31&page_size=2500" -H "Authorization: Api-Key YOUR_API_KEY"

Using Python

import requests

url = "https://jobdataapi.com/api/jobsexpired/"
params = {
    "country_code": "US",
    "expired_since": "2024-01-01",
    "expired_until": "2024-01-31",
    "page_size": 2500
}
headers = {"Authorization": "Api-Key YOUR_API_KEY"}

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

print(data)

Replace YOUR_API_KEY with your actual pro access API key.

Parameters

The Expired Jobs endpoint supports several query parameters to filter the results according to your needs:

• country_code: Filters results by the country code (ISO 3166-1 alpha-2 code, see Job Countries endpoint for more info).
• region_id: Filters results based on the job region (see Job Regions endpoint for more info).
• expired_since: Limits the search to jobs expired on or after this date. Format: YYYY-MM-DD.
• expired_until: Limits the search to jobs expired on or before this date. Format: YYYY-MM-DD.
• has_remote: Boolean flag to include jobs that offer remote work options.
• language: Filters results based on the job listing's language (ISO 639 language code, e.g. en, fr, de, etc. - see all available codes on the langauge stats page).
• max_age: Specifies the maximum age of the job listing before it expired, in days.
• published_since: Filters jobs that were published on or after this date. Format: YYYY-MM-DD.
• published_until: Filters jobs that were published on or before this date. Format: YYYY-MM-DD.
• 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 of results to return - requires a valid access pro API key, otherwise using this parameter will return an empty result.
• page_size: Determines the number of results per page (1 - 5000, default: 200) - requires a valid access pro API key, otherwise using this parameter will return an empty result.

Response

The response from the Expired Jobs endpoint is a JSON object containing a list of expired job postings. Each entry includes details such as the job ID, external ID, the date it expired, the date it was published, the job title, and the application URL.

In case of querying a single job via its ID (through /api/jobsexpired/{id}/) a full JSON response will be returned in case the job has expired. If not a 404 response (not found) will be returned, which means no expired info exists for that given job and the listing is still live.

Response Structure

The API employs pagination to manage large sets of results efficiently, making the data easier to handle by breaking it into smaller, manageable pages. The paginated response includes:

• count: An integer representing the total number of expired job postings that match the query criteria. This helps in understanding the scope of the data and planning navigation through paginated results.
• next: A URL string pointing to the next page of results. This is particularly useful for iterative fetching in applications that process or display large datasets. It will be null if there is no next page.
• previous: A URL string pointing to the previous page of results. Similar to next, it assists in navigating through pages but in the reverse direction. It will be null on the first page.
• results: An array of objects, each representing an expired job posting. This array holds the actual data you're interested in and may contain multiple job postings, depending on the page_size specified in the request.

Job Postings (results Array)

Each object in the results array provides detailed information about a specific expired job posting:

• id: A unique integer identifier for the job posting within the jobdata API system. This ID can be used for referencing or querying specific job postings in other API operations.
• ext_id: A string representing an external identifier for the job posting, if available. This could be useful for correlating job postings with external systems or databases.
• expired: A string in ISO 8601 date format (YYYY-MM-DDTHH:MM:SSZ), indicating when the job posting expired. This timestamp is crucial for understanding the timing of job postings and their relevance.
• published: A string in ISO 8601 date format (YYYY-MM-DDTHH:MM:SSZ), showing when the job posting was initially published. Analyzing the duration between published and expired can provide insights into how long job opportunities typically remain open.
• title: A string containing the title of the job posting. This gives a quick overview of the job's nature or position.
• application_url: A URL string where candidates could have applied for the job or obtained more information. While the job is expired, this link may still offer insights into the employer's hiring process or lead to similar, active opportunities.

Example Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 12345,
      "ext_id": "XYZ987",
      "expired": "2024-02-08T03:55:02.619747Z",
      "published": "2024-01-12T20:49:08Z",
      "title": "Software Engineer",
      "application_url": "https://example.com/job/12345/apply"
    },
    {
      "id": 67890,
      "ext_id": "ABC123",
      "expired": "2024-02-08T03:55:02.619747Z",
      "published": "2023-12-17T20:50:19Z",
      "title": "Product Manager",
      "application_url": "https://example.com/job/67890/apply"
    }
  ]
}

Use Cases

• Job Search Platforms: Automatically remove or archive listings that have expired, maintaining a current and relevant job board for users.
• HR Software: Monitor the lifecycle of job postings to optimize posting strategies and improve candidate attraction.
• Market Research: Analyze job expiration data to identify hiring trends, peak hiring seasons, and the average duration jobs stay posted.

Notes

• The expired_since and expired_until parameters can be used together to define a specific date range for the expired job posts you're interested in.
• To filter by a sequence of job IDs the min_id and max_id parameters can be used to define a range, offset or limit here instead of - or combined with - date filter query parameters.
• The has_remote parameter is particularly useful for platforms focusing on remote work opportunities.
• Pagination parameters (page and page_size) are essential for handling large datasets and improving the manageability of the API response.
• This endpoint is only accessible to users with an access pro subscription to the jobdata API.
• It is crucial to replace YOUR_API_KEY with your actual jobdata API key in the authorization header to successfully make requests.

This documentation section provides a comprehensive overview of the Expired Jobs endpoint, ensuring that developers and businesses can effectively utilize this feature to enhance their services or gain insights into job market trends.

Related Docs