Skip to main content
API docs by Redocly

Search API (2.1.0)

Download OpenAPI specification:Download

The API allows for a constant stream of up-to-date job postings and provides the best matching based on any job seeker's search query. With the API, you use the Jobs2Careers enhanced search engine which has years of optimizations already built in. The API takes the guess work out of everything!

Note: To retrieve a specific job by its ID, please use the Platform API.

Search Parameter Behavior for Publishers: Our search API utilizes advanced machine learning algorithms to deliver the most relevant job matches. Many search parameters function as ranking signals that help optimize result relevance rather than strict exclusion filters. This approach ensures publishers receive the highest quality, most personalized job recommendations for their users while maintaining optimal search performance.

Search API

Programmatic access to millions of jobs via Talroo's Search API

/api/search.php

query Parameters
id
required
integer

Your unique Publisher ID (as shown in the Feed Manager).

pass
required
string

Your unique Publisher Password (as shown in the Feed Manager).

ip
required
string

The end user's IP address. Used for location if l is not present, and also used for analytics and security.

q
required
string

URL encoded query string (keyword).

[Required if l is NOT present.]

l
required
string

Combination of city state (Austin,TX) or zipcode (78750).

[Required if q is NOT present.]

pid
string

Persistent user-level identifier used to enable personalized search results.

  • Not a publisher ID (account-level) or a query ID (per-request)
  • Should be stable for the same user across sessions for optimal results
  • Do NOT use raw email or simple hash(user_id); avoid sending PII
  • Recommended: a deterministic, non-reversible value such as an SHA256 hash of a profile ID with salt (a secret static string)

For example, sha256("hello_world_1234567890")

uid
string
Deprecated

DEPRECATED: This parameter was originally intended to enable user-level personalization in search results but has been migrated to the pid parameter. Please use the pid parameter for all personalization use cases. Do not use uid.

benefit
string

Help influence search results based on job seeker's preferences of specific benefits.

Multiple signals may be provided and separated by the pipe (|) symbol with no spaces.

Allowed Values:

  • any
  • healthcare
  • pto
  • education
  • childcare
  • retirement

Note: This parameter does not act as a hard filter, but rather a signal to influence search results.

commute
integer

Filter search results to only show jobs within the specified maximum commute time to the job location.

The value is specified in minutes and will be automatically translated to the nearest supported commute time option.

Supported Values:

  • 15
  • 30
  • 45
  • 60

Any input value will be mapped to the closest supported option (e.g., 5 minutes becomes 15, 40 minutes becomes 45, 70 minutes becomes 60).

This parameter will override the d (distance) parameter. Commute times are based on average traffic conditions and may be inaccurate during peak hours.

d
integer

Only display jobs that are within a radius of the specified value (in kilometers) from the search location. The "search location" is defined as either the value of the l parameter or the determined location of the user executing the search (if no l is specified). The value is specified in kilometers (km). In rural areas, this distance may be automatically expanded to ensure adequate job results. Note: This parameter is overridden when the commute parameter is present. Allowed Values:

  • 8 (05 miles)
  • 16 (10 miles)
  • 20 (12 miles)
  • 24 (15 miles)
  • 32 (20 miles)
  • 40 (24 miles)
  • 48 (30 miles)
  • 56 (35 miles)
  • 80 (50 miles)
date
integer
Deprecated

DEPRECATED: This parameter is deprecated and should not be used. Job dates are inconsistent due to reposting.

encrypt
integer
Enum: 0 1

Enable/disable encryption of user information passed via query parameters.

format
string
Default: "json"
Enum: "html" "json" "xml"

Output Format:

  • xml
    • Content-Type: application/xml
  • json
    • Content-Type: application/json
  • html
    • Content-Type: text/html
full_desc
integer
Enum: 0 1

Include the full job description in the response instead of just a 256-character snippet.

skip_desc
integer
Enum: 0 1

Skip the description in the response body to help improve response time. If this is set to 1, it will overwrite the full_desc parameter if it exists and skip the description. The response will still contain the description key for each job but the value will be "..."

limit
integer [ 0 .. 200 ]
Default: 10

Number of jobs to return in the result set. Usually used in combination with the start parameter to allow for paging.

link
integer
Enum: 0 1

Expose a direct link. Removes the onclick attribute and replaces it with a url attribute.

logo
integer
Enum: 0 1

Adds the logo_url attribute to the jobs in the response.

salary
number >= 0

Help influence search results based on job seeker's salary preferences.

Using salary by itself is equivalent to setting salary.period to hourly and salary.min to the specified value.

Note: This parameter does not act as a hard filter, but rather a signal to influence search results.

salary.min
number >= 0

Help influence search results based on job seeker's preferences for jobs which have a minimum salary for the specified salary.period greater than or equal to the specified value.

  • Used in combination with the salary.period and salary.max parameters.
  • Not used with the basic salary parameter`.

Note: This parameter does not act as a hard filter, but rather a signal to influence search results.

salary.max
number >= 0

Help influence search results based on job seeker's preferences for jobs which have a maximum salary for the specified salary.period less than or equal to the specified value.

  • Used in combination with the salary.period and salary.min parameters.
  • Should only be used in conjunction with the salary.min parameter
  • Not used with the basic salary parameter.

Note: This parameter does not act as a hard filter, but rather a signal to influence search results.

salary.period
string
Default: "hourly"

Help influence search results based on job seeker's preferences for jobs which have a specified salary period type. This parameter may be used with all other salary field types.

Specifying a salary.period of any will signal preference for any jobs with salary or bonus periods of any type that have a salary.min value greater than or equal to the specified salary.min value.

Multiple salary.period values are not supported; only a single value can be specified.

Allowed Values:

  • any
  • hourly
  • daily
  • weekly
  • monthly
  • yearly
  • bonus

Note: This parameter does not act as a hard filter, but rather a signal to influence search results.

start
integer >= 0
Default: 0

Start offset. Used in combination with the limit parameter for paging through results.

t1
string <= 32 characters

Tracking tag 1.

t2
string <= 32 characters

Tracking tag 2.

t3
string <= 32 characters

Tracking tag 3.

useragent
string

Pass in the user agent to prioritize jobs for mobile platforms

worktype
string

Help influence search results based on the presence or absence of specific work types.

Multiple values may be entered and separated by the pipe (|) symbol with no spaces.

Allowed Values:

  • any
  • fulltime
  • parttime
  • internship
  • workfromhome
  • gig
  • entrylevel
  • noexperience

Note: This parameter does not act as a hard filter, but rather a signal to influence search results.

extractions
integer
Enum: 0 1

Will return additional fields in the response on each job.

Additional fields:

  • all_requirements_normalized: String of a json object of the normalized requirements for the job extracted from the job description.
  • all_preferences_normalized: String of a json object of the normalized preferences for the job extracted from the job description.
  • work_schedule: String of the work schedule for the job extracted from the job description.
  • visa_status: String of the visa status for the job extracted from the job description.
  • benefits: String of the benefits for the job extracted from the job description.
  • work_location_type: String of the work location type for the job extracted from the job description.
  • compensation: String of a compensation description for the job extracted from the job description.

Note: The field values are not guaranteed to be present on every job.

Responses

Response samples

Content type
{
  "total": 4951,
  "start": 0,
  "count": 1,
  "jobs": [
    {
      "title": "Part Time Delivery Job - Earn up to $25/hr",
      "date": "2019-01-02T19:03:25Z",
      "onclick": "j2c_view(1895935481, 2429914811, 4316464402, undefined, undefined, undefined, undefined, undefined, undefined, '&job_loc=Austin%2CTX','2d04486c08affd792f75778ec21a4f10')",
      "company": "Shipt",
      "city": [
        "Austin,TX"
      ],
      "coordinates": [
        "30.2907,-97.7648"
      ],
      "description": "Shipt is a membership-based marketplace that helps people get the things they need, like fresh produce and household essentials, from stores they trust. Help people save time and have fun while you're at it - there's never been a better time to join",
      "price": "high",
      "preview": 0,
      "major_category0": "[Caregiving/Babysitting]",
      "minor_category0": "[Caregiving/Babysitting] Babysitter/Child Caregiver",
      "major_category1": "[Trucking]",
      "minor_category1": "[Trucking] Delivery Driver",
      "salary_details": [
        {
          "value": [
            "20.00",
            "25.00"
          ],
          "unit": "hourly",
          "label": "$20-$25/hr"
        }
      ],
      "benefit_details": [
        {
          "value": true,
          "unit": "healthcare",
          "label": "Health Insurance"
        },
        {
          "value": true,
          "unit": "pto",
          "label": "Paid Time Off"
        }
      ],
      "skills_details": [
        {
          "value": true,
          "unit": "driver_license",
          "label": "Driver License",
          "key": "dri_3d3863bf3c",
          "id": 11000
        }
      ],
      "worktype_details": [
        {
          "value": true,
          "unit": "fulltime",
          "label": "Full Time"
        }
      ],
      "id": "5957639185"
    }
  ]
}

BenefitDetails

value
boolean
unit
string

Supported Types healthcare, pto, education, childcare, retirement

label
string
{
  • "value": true,
  • "unit": "string",
  • "label": "string"
}

Error

status
string
message
string
{
  • "status": "string",
  • "message": "string"
}

Job

title
string
date
string
onclick
string
url
string
company
string
city
Array of strings
coordinates
Array of strings
description
string
price
string
preview
integer
id
string
ad_type
string
major_category0
string
major_category1
string
minor_category0
string
minor_category1
string
Array of objects (BenefitDetails)
Array of objects (SalaryDetails)
Array of objects (SkillsDetails)
Array of objects (WorktypeDetails)
logo_url
string
{
  • "title": "string",
  • "date": "string",
  • "onclick": "string",
  • "url": "string",
  • "company": "string",
  • "city": [
    ],
  • "coordinates": [
    ],
  • "description": "string",
  • "price": "string",
  • "preview": 0,
  • "id": "string",
  • "ad_type": "string",
  • "major_category0": "string",
  • "major_category1": "string",
  • "minor_category0": "string",
  • "minor_category1": "string",
  • "benefit_details": [
    ],
  • "salary_details": [
    ],
  • "skills_details": [
    ],
  • "worktype_details": [
    ],
  • "logo_url": "string"
}

JobArray

Array
title
string
date
string
onclick
string
url
string
company
string
city
Array of strings
coordinates
Array of strings
description
string
price
string
preview
integer
id
string
ad_type
string
major_category0
string
major_category1
string
minor_category0
string
minor_category1
string
Array of objects (BenefitDetails)
Array of objects (SalaryDetails)
Array of objects (SkillsDetails)
Array of objects (WorktypeDetails)
logo_url
string
[
  • {
    }
]

JobSearch

total
integer
start
integer
count
integer
Array of objects (JobArray)
{
  • "total": 4951,
  • "start": 0,
  • "count": 1,
  • "jobs": [
    ]
}

SalaryDetails

value
Array of strings
unit
string

Supported Types bonus, yearly, monthly, weekly, daily, hourly

label
string
{
  • "value": [
    ],
  • "unit": "string",
  • "label": "string"
}

SkillsDetails

value
boolean
unit
string

Supported Types age, background_check, certification_license, driver_license, education, experience, experience_range, general, language, other_skill, physical, shift_type

label
string
key
string
id
integer
{
  • "value": true,
  • "unit": "string",
  • "label": "string",
  • "key": "string",
  • "id": 0
}

WorktypeDetails

value
boolean
unit
string

Supported Types fulltime, parttime, internship, workfromhome, gig, entrylevel, noexperience

label
string
{
  • "value": true,
  • "unit": "string",
  • "label": "string"
}