Full-Text Search on Job Descriptions

Table of contents

Introduction

The jobdata API's /api/jobs/ endpoint features a full-text search capability available for access pro subscribers. This functionality enables users to perform detailed and nuanced searches within job descriptions. This section provides comprehensive guidance on using the description query parameter to refine your job search with precision.

Search Index

The search index is built from two key job data fields: the description_string, which is a cleaned version of the job description stripped of any HTML tags and non-text elements, ensuring that the search focuses solely on the relevant textual content, and the title, which is also included in the search index to enhance the relevance of search results. By leveraging both the cleaned job description and the job title, the full-text search capability allows users to perform nuanced queries that effectively match job listings based on specific skills, phrases, or keywords.

Endpoint Overview

URL: /api/jobs/

Method: GET

Authorization Required: Yes (access pro subscription)

Description: This endpoint is essential to find jobs that match specific criteria, such as required skills, job titles, or phrases mentioned within job descriptions.

Query Parameter

• description (string, optional): Executes full-text search queries against job descriptions.

How Full-Text Search Operates

The description parameter leverages full-text search capabilities, translating user queries into powerful search operations that understand logical operators and phrase matching. The parameter supports:

• Unquoted text: Terms not enclosed in quotes are treated as separate search terms (will be converted to terms separated by & operators internally).

• "Quoted text": Text within quotes is treated as a single search phrase.

• OR: The word "or" between terms allows for searches that match any of the specified terms.

• - (Dash): A dash before a term translates to the ! operator, excluding terms from search results.

Example Usage

Simple Keyword Search

Using curl

curl -X GET "https://jobdataapi.com/api/jobs/?description=python+django" \
     -H "Authorization: Api-Key YOUR_API_KEY"

Using Python

import requests

url = "https://jobdataapi.com/api/jobs/"
params = {
    "description": "python django"
}
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}

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

This query searches for job descriptions containing both "python" and "django".

Phrase Search

Using curl

curl -X GET "https://jobdataapi.com/api/jobs/?description=%22senior+developer%22" \
     -H "Authorization: Api-Key YOUR_API_KEY"

Using Python

import requests

url = "https://jobdataapi.com/api/jobs/"
params = {
    "description": '"senior developer"'
}
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}

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

Searches for jobs where "senior" and "developer" appear as a consecutive phrase.

Combining Keywords and Phrases

Using curl

curl -X GET "https://jobdataapi.com/api/jobs/?description=python+%22software+engineer%22" \
     -H "Authorization: Api-Key YOUR_API_KEY"

Using Python

import requests

url = "https://jobdataapi.com/api/jobs/"
params = {
    "description": 'python "software engineer"'
}
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}

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

Finds jobs mentioning "python" and the exact phrase "software engineer".

Including and Excluding Terms

Using curl

curl -X GET "https://jobdataapi.com/api/jobs/?description=python+-java+OR+ruby+-java" \
     -H "Authorization: Api-Key YOUR_API_KEY"

Using Python

import requests

url = "https://jobdataapi.com/api/jobs/"
params = {
    "description": 'python -java OR ruby -java'
}
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}

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

Looks for jobs mentioning either "python" or "ruby" but excludes any jobs mentioning "java".

Response

Upon successfully executing a search query against the /api/jobs/ endpoint, the API returns a structured JSON response containing a paginated list of job listings that match the provided search criteria. Each job listing within the response is comprehensive, offering detailed information about the position, including the full job description.

{
  "count": 123,
  "next": "https://jobdataapi.com/api/jobs/?page=2",
  "previous": null,
  "results": [
    {
      "id": 1,
      "company": {
        "name": "Company A",
        "logo": "URL_to_logo",
        "website_url": "URL_to_company_website",
        ...
      },
      "title": "Job Title",
      "location": "Job Location",
      "description": "Full job description text here, detailing responsibilities, qualifications, and other important information..."
      ...
    },
    ...
  ]
}

Tips for Crafting Effective Queries

• Unquoted vs. Quoted: Use unquoted text for broad searches across multiple terms and quoted text for precise phrase matches.
• Logical Operators: Utilize "OR" and "-" to expand or narrow your search scope as needed.
• Experimentation: Different combinations of keywords, phrases, and operators can yield varied and sometimes more relevant results.

Notes

• Access to this search requires authentication via the Authorization header, including a valid API key. Replace YOUR_API_KEY with your actual API key in the sample requests.
• A full-text search query can be combined with any of the other query parameters available on the /api/jobs/ endpoint.
• This feature is available to access pro subscribers only (without it, using the description parameter returns an empty result).

Leveraging the full-text search feature enhances job discovery by enabling detailed queries across the extensive database of job descriptions. This allows users to pinpoint jobs that align closely with their skills, experiences, and career aspirations.

Related Docs