swagger: '2.0'
info:
  title: Search API
  version: 2.1.0
  description: >

    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](https://docs.talroo.com/api/platform/v5#tag/Jobs/operation/getJobById).


    **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.
schemes:
  - https
host: api.jobs2careers.com
basePath: /api
paths:
  /search.php:
    get:
      tags:
        - Search
      summary: /api/search.php
      parameters:
        - in: query
          name: id
          required: true
          type: integer
          description: Your unique Publisher ID (as shown in the Feed Manager).
        - in: query
          name: pass
          required: true
          type: string
          description: Your unique Publisher Password (as shown in the Feed Manager).
        - in: query
          name: ip
          required: true
          type: string
          description: >-
            The end user's IP address. Used for location if `l` is not present,
            and also used for analytics and security.
        - in: query
          name: q
          required: true
          type: string
          description: |
            URL encoded query string (keyword). 

            [**Required if `l` is NOT present.**]
        - in: query
          name: l
          required: true
          type: string
          description: |
            Combination of city state (`Austin,TX`) or zipcode (`78750`). 

            [**Required if `q` is NOT present.**]
        - in: query
          name: pid
          type: string
          description: >
            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")`
        - in: query
          name: uid
          type: string
          deprecated: true
          description: >
            **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`.
        - in: query
          name: benefit
          collectionFormat: pipes
          type: string
          description: >
            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.**_
        - in: query
          name: commute
          type: integer
          description: >
            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.**_
        - in: query
          name: d
          type: integer
          description: >
            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)
        - in: query
          name: date
          type: integer
          deprecated: true
          description: >
            **DEPRECATED:** This parameter is deprecated and should not be used.
            Job dates are inconsistent due to reposting.
        - in: query
          name: encrypt
          type: integer
          enum:
            - 0
            - 1
          description: >-
            Enable/disable encryption of user information passed via query
            parameters.
        - in: query
          name: format
          type: string
          enum:
            - xml
            - json
            - html
          default: json
          description: |
            Output Format:
              * `xml`
                 * Content-Type: application/xml
              * `json`
                 * Content-Type: application/json
              * `html`
                 * Content-Type: text/html
        - in: query
          name: full_desc
          type: integer
          enum:
            - 0
            - 1
          description: >-
            Include the full job description in the response instead of just a
            256-character snippet.
        - in: query
          name: skip_desc
          type: integer
          enum:
            - 0
            - 1
          description: >-
            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
            "..."
        - in: query
          name: limit
          type: integer
          default: 10
          minimum: 0
          maximum: 200
          description: >-
            Number of jobs to return in the result set. Usually used in
            combination with the `start` parameter to allow for paging.
        - in: query
          name: link
          type: integer
          enum:
            - 0
            - 1
          description: >-
            Expose a direct link. Removes the `onclick` attribute and replaces
            it with a `url` attribute.
        - in: query
          name: logo
          type: integer
          enum:
            - 0
            - 1
          description: Adds the `logo_url` attribute to the jobs in the response.
        - in: query
          name: salary
          type: number
          minimum: 0
          description: >
            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.**_
        - in: query
          name: salary.min
          type: number
          minimum: 0
          description: >
            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.**_
        - in: query
          name: salary.max
          type: number
          minimum: 0
          description: >
            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.**_     
        - in: query
          name: salary.period
          type: string
          default: hourly
          description: >
            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.**_
        - in: query
          name: start
          type: integer
          default: 0
          minimum: 0
          description: >-
            Start offset. Used in combination with the `limit` parameter for
            paging through results.
        - in: query
          name: t1
          type: string
          maxLength: 32
          description: Tracking tag `1`.
        - in: query
          name: t2
          type: string
          maxLength: 32
          description: Tracking tag `2`.
        - in: query
          name: t3
          type: string
          maxLength: 32
          description: Tracking tag `3`.
        - in: query
          name: useragent
          type: string
          description: Pass in the user agent to prioritize jobs for mobile platforms
        - in: query
          name: worktype
          collectionFormat: pipes
          type: string
          description: >
            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.**_
        - in: query
          name: extractions
          type: integer
          enum:
            - 0
            - 1
          description: >
            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:
        '200':
          description: Success
          examples:
            '*/*':
              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'
            application/json:
              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'
            application/xml: |
              <result total="5069" start="0" count="1">
                <job>
                  <title><![CDATA[Part-Time Delivery Driver - Make up to $18/hr]]></title>
                  <date>2019-01-03T07:03:22Z</date>
                  <url>https://www.jobs2careers.com/click.php?jid=encrypted_string&other_click_params=things</url>
                  <company><![CDATA[Favor Delivery]]></company>
                  <city>Austin,TX</city>
                  <coordinates><![CDATA[30.2907,-97.7648]]></coordinates>
                  <description><![CDATA[We deliver anything our customers need: tacos, groceries, dry cleaning, you name it! We're personal assistants, not delivery drivers.]]></description>
                  <price preview="0">high</price>
                  <major_category0>[Trucking]</major_category0>
                  <minor_category0>[Trucking] Delivery Driver</minor_category0>
                  <salary_details>
                    <item>
                        <value_min>15.00</value_min>
                        <value_max>20.00</value_max>
                        <unit>hourly</unit>
                        <label>$15-$20/hr</label>
                    </item>
                  </salary_details>
                  <benefit_details>
                    <item>
                        <value>true</value>
                        <unit>healthcare</unit>
                        <label>Health Insurance</label>
                    </item>
                    <item>
                        <value>true</value>
                        <unit>pto</unit>
                        <label>Paid Time Off</label>
                    </item>
                  </benefit_details>
                  <worktype_details>
                    <item>
                        <value>true</value>
                        <unit>fulltime</unit>
                        <label>Full Time</label>
                    </item>
                  </worktype_details> 
                  <skills_details>
                      <item>
                          <value>true</value>
                          <unit>driver_license</unit>
                          <label>Driver License</label>
                          <key>dri_3d3863bf3c</key>
                          <id>11000</id>
                      </item>
                  </skills_details>                  
                  <id><![CDATA[6209600845]]></id>
                </job>
              </result>
          schema:
            $ref: '#/definitions/JobSearch'
        '400':
          description: Bad request
          examples:
            '*/*':
              status: error
              message: Bad format, provide q or l
            application/json:
              status: error
              message: Bad format, provide q or l
          schema:
            $ref: '#/definitions/Error'
definitions:
  Error:
    type: object
    properties:
      status:
        type: string
      message:
        type: string
  JobSearch:
    type: object
    properties:
      total:
        type: integer
      start:
        type: integer
      count:
        type: integer
      jobs:
        $ref: '#/definitions/JobArray'
    xml:
      name: result
    example:
      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
          worktype_details:
            - value: true
              unit: fulltime
              label: Full Time
          skills_details:
            - value: true
              unit: driver_license
              label: Driver License
              key: dri_3d3863bf3c
              id: 11000
          id: '5957639185'
  JobArray:
    type: array
    items:
      $ref: '#/definitions/Job'
  Job:
    type: object
    properties:
      title:
        type: string
      date:
        type: string
      onclick:
        type: string
      url:
        type: string
      company:
        type: string
      city:
        type: array
        items:
          type: string
      coordinates:
        type: array
        items:
          type: string
      description:
        type: string
      price:
        type: string
      preview:
        type: integer
      id:
        type: string
      ad_type:
        type: string
      major_category0:
        type: string
      major_category1:
        type: string
      minor_category0:
        type: string
      minor_category1:
        type: string
      benefit_details:
        type: array
        items:
          $ref: '#/definitions/BenefitDetails'
      salary_details:
        type: array
        items:
          $ref: '#/definitions/SalaryDetails'
      skills_details:
        type: array
        items:
          $ref: '#/definitions/SkillsDetails'
      worktype_details:
        type: array
        items:
          $ref: '#/definitions/WorktypeDetails'
      logo_url:
        type: string
  BenefitDetails:
    type: object
    properties:
      value:
        type: boolean
      unit:
        type: string
        description: >-
          Supported Types `healthcare`, `pto`, `education`, `childcare`,
          `retirement`
      label:
        type: string
  SalaryDetails:
    type: object
    properties:
      value:
        type: array
        items:
          type: string
          description: '["min salary value", "max salary value"]'
      unit:
        type: string
        description: >-
          Supported Types `bonus`, `yearly`, `monthly`, `weekly`, `daily`,
          `hourly`
      label:
        type: string
  SkillsDetails:
    type: object
    properties:
      value:
        type: boolean
      unit:
        type: string
        description: >-
          Supported Types `age`, `background_check`, `certification_license`,
          `driver_license`, `education`, `experience`, `experience_range`,
          `general`, `language`, `other_skill`, `physical`, `shift_type`
      label:
        type: string
      key:
        type: string
      id:
        type: integer
  WorktypeDetails:
    type: object
    properties:
      value:
        type: boolean
      unit:
        type: string
        description: >-
          Supported Types `fulltime`, `parttime`, `internship`, `workfromhome`,
          `gig`, `entrylevel`, `noexperience`
      label:
        type: string
tags:
  - name: Search
    x-displayName: Search API
    description: Programmatic access to millions of jobs via Talroo's Search API
  - name: Error
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Error" />
  - name: JobSearch
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/JobSearch" />
  - name: JobArray
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/JobArray" />
  - name: Job
    x-displayName: Job
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Job" />
  - name: BenefitDetails
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/BenefitDetails" />
  - name: SalaryDetails
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/SalaryDetails" />
  - name: SkillsDetails
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/SkillsDetails" />
  - name: WorktypeDetails
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/WorktypeDetails" />
x-tagGroups:
  - name: Endpoints
    tags:
      - Search
  - name: Models
    tags:
      - Error
      - JobSearch
      - JobArray
      - Job
      - BenefitDetails
      - SalaryDetails
      - SkillsDetails
      - WorktypeDetails
