openapi: 3.0.0
info:
  title: LinkedIn Jobs API
  description: |
    Search LinkedIn job listings by keyword and location.

    Narrow the jobs by posting date, distance and hiring company. Each job carries its LinkedIn job id, title, company, location, posting date and link. The first page returns up to 60 jobs, and each later page returns up to 10.

    **Filters**: the `filters` block lists companies hiring for the search. Pass an option's `value` as the `company_id` parameter to keep only that company's jobs.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: LinkedIn Jobs Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: 'Search engine. Must be set to: `linkedin_jobs`'
          schema:
            type: string
            enum: ["linkedin_jobs"]
        - name: q
          in: query
          required: false
          description: Keywords to search for, such as a job title, a skill or a company name.
          schema:
            type: string
            maxLength: 500
        - name: location
          in: query
          required: false
          description: City, region or country to search jobs in. LinkedIn matches the text to one of its own locations, and `search_parameters.location_used` names the place it searched. Use `location_id` instead to set an exact location. Without either, jobs are searched worldwide.
          schema:
            type: string
            maxLength: 200
        - name: location_id
          in: query
          required: false
          description: LinkedIn location id, the `geoId` value in a LinkedIn job search URL. For example, `103644278` is the United States. Use either `location` or `location_id`.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
        - name: time_period
          in: query
          required: false
          description: Filter results by how recently the job was posted.
          schema:
            type: string
            enum: ["last_hour", "last_day", "last_week", "last_month"]
        - name: distance
          in: query
          required: false
          description: Search radius around a city, in miles. LinkedIn uses 50 miles when it is not set and ignores it for a country. Requires `location` or `location_id`.
          schema:
            type: string
            enum: ["10", "25", "50", "100"]
        - name: company_id
          in: query
          required: false
          description: LinkedIn company ids separated by commas, up to 50. Returns jobs from any of the companies. Each option in the `filters` block carries a company id as its `value`.
          schema:
            type: string
            pattern: '^[0-9]{1,10}(,[0-9]{1,10}){0,49}$'
        - name: page
          in: query
          required: false
          description: Page number for pagination, from 1 to 95. Page 1 returns up to 60 jobs and each later page up to 10. Later pages return `jobs` and `pagination` only.
          schema:
            type: integer
            minimum: 1
            maximum: 95
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        search_information:
          $ref: '#/components/schemas/SearchInformation'
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/Job'
          description: "Jobs on this page, in LinkedIn's order"
        filters:
          type: array
          items:
            $ref: '#/components/schemas/Filter'
          description: "Company filter LinkedIn offers for the search"
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: "Error message if the request failed"
    SearchMetadata:
      type: object
      required: [id, status, created_at]
      properties:
        id:
          type: string
          description: "Unique identifier for the search request"
        status:
          type: string
          description: "Status of the search request"
        created_at:
          type: string
          format: date-time
          description: "Timestamp when the search was created"
        request_time_taken:
          type: number
          description: "Time taken to make the request in seconds"
        parsing_time_taken:
          type: number
          description: "Time taken to parse the results in seconds"
        total_time_taken:
          type: number
          description: "Total time taken for the search in seconds"
        request_url:
          type: string
          description: "LinkedIn URL for this search"
        html_url:
          type: string
          description: "URL to view HTML results"
        json_url:
          type: string
          description: "URL to view JSON results"
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: "Search engine used"
        q:
          type: string
          description: "Keywords searched"
        location:
          type: string
          description: "Location searched"
        location_used:
          type: string
          description: "Place LinkedIn searched, as LinkedIn names it"
        location_id:
          type: string
          description: "LinkedIn location id searched"
        time_period:
          type: string
          description: "Time period filter applied"
        distance:
          type: string
          description: "Search radius in miles"
        company_id:
          type: string
          description: "LinkedIn company ids applied"
        page:
          type: string
          description: "Page number"
    SearchInformation:
      type: object
      required: [total_results]
      properties:
        total_results:
          type: integer
          description: "Number of jobs LinkedIn shows for the search, rounded down for large counts"
        is_total_results_approximate:
          type: boolean
          description: "True when LinkedIn rounds the total and shows a plus sign, as in 11,000+"
    Job:
      type: object
      required: [position, job_id, title, company_name, location, date, posted_at, link]
      properties:
        position:
          type: integer
          description: "Position of the job on this page"
        job_id:
          type: string
          description: "LinkedIn job id"
        title:
          type: string
          description: "Job title"
        company_name:
          type: string
          description: "Name of the hiring company"
        company_link:
          type: string
          description: "LinkedIn page of the hiring company"
        location:
          type: string
          description: "Location of the job as LinkedIn shows it"
        date:
          type: string
          format: date
          description: "Date the job was posted, in YYYY-MM-DD format"
        posted_at:
          type: string
          description: "How long ago the job was posted, as LinkedIn shows it"
        link:
          type: string
          description: "LinkedIn page of the job"
        thumbnail:
          type: string
          description: "Logo of the hiring company"
    Filter:
      type: object
      required: [key, options]
      properties:
        key:
          type: string
          description: "Parameter that takes the value of an option"
        options:
          type: array
          items:
            $ref: '#/components/schemas/FilterOption'
          description: "Options LinkedIn offers in this filter"
    FilterOption:
      type: object
      required: [text, value]
      properties:
        text:
          type: string
          description: "Option label as LinkedIn shows it"
        value:
          type: string
          description: "Value to pass to the parameter named by the filter's key"
        is_selected:
          type: boolean
          description: "Whether the option is applied to this search"
    Pagination:
      type: object
      required: [current]
      properties:
        current:
          type: integer
          description: "Number of this page"
        previous:
          type: string
          description: "LinkedIn URL of the previous page"
        next:
          type: string
          description: "LinkedIn URL of the next page"
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong