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

    Each job returns the title, company, location, job type, benefits, salary, posting date, description and a link to the posting. Use `gl` to search a country's Indeed site.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Indeed Jobs Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: 'Search engine. Must be set to: `indeed_jobs`'
          schema:
            type: string
            enum: ["indeed_jobs"]
        - name: q
          in: query
          required: true
          description: Keywords to search for, such as a job title, a skill or a company name.
          schema:
            type: string
        - name: location
          in: query
          required: false
          description: City, region or ZIP code to search jobs in.
          schema:
            type: string
        - name: gl
          in: query
          required: false
          description: Country whose Indeed site to search, as an ISO 3166-1 alpha-2 code.
          schema:
            type: string
            enum: ["us", "gb", "ca", "au", "ie", "nz", "in", "sg", "ph", "my", "hk", "pk", "de", "fr", "es", "it", "nl", "be", "at", "ch", "pl", "se", "no", "dk", "fi", "pt", "ro", "cz", "hu", "gr", "br", "mx", "ar", "cl", "co", "pe", "jp", "kr", "tr", "ae", "sa", "za", "ng", "eg", "il"]
            default: "us"
      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'
    SearchMetadata:
      type: object
      required: [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: "Indeed 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 for the request.
        q:
          type: string
          description: Keywords the search was run for.
        location:
          type: string
          description: Location the search was run for.
        gl:
          type: string
          description: Country whose Indeed site was searched.
    SearchInformation:
      type: object
      properties:
        query_displayed:
          type: string
          description: Keywords Indeed ran the search for.
        location_displayed:
          type: string
          description: Location Indeed ran the search for.
        page:
          type: integer
          description: Page number of the results.
        total_results:
          type: integer
          description: Total number of jobs matching the search.
    Job:
      type: object
      required: [position, job_id, title, location, posted_at, link, is_sponsored]
      properties:
        position:
          type: integer
          description: Position of the job in the results.
        job_id:
          type: string
          description: Indeed identifier for the job.
        title:
          type: string
          description: Job title.
        company_name:
          type: string
          description: Name of the hiring company.
        company_link:
          type: string
          description: Link to the company page on Indeed.
        company_logo:
          type: string
          description: URL of the company logo.
        company_rating:
          type: number
          description: Average company rating out of five.
        company_reviews:
          type: integer
          description: Number of company reviews.
        location:
          type: string
          description: Job location as shown on Indeed.
        city:
          type: string
          description: City of the job.
        state:
          type: string
          description: State or region of the job.
        country:
          type: string
          description: Country code of the job.
        is_remote:
          type: boolean
          description: Whether the job is fully remote.
        is_hybrid:
          type: boolean
          description: Whether the job is hybrid.
        postal_code:
          type: string
          description: Postal code of the job.
        neighborhood:
          type: string
          description: Neighborhood of the job.
        working_hours:
          type: object
          description: Working hours stated for the job.
          properties:
            min:
              type: number
              description: Minimum hours.
            max:
              type: number
              description: Maximum hours.
            period:
              type: string
              description: Period the hours apply to.
        requirements:
          type: array
          description: Requirements listed for the job.
          items:
            type: string
        is_easy_apply:
          type: boolean
          description: Whether candidates can apply on Indeed.
        is_responsive_employer:
          type: boolean
          description: Whether Indeed marks the employer as responsive.
        job_types:
          type: array
          description: Employment types of the job.
          items:
            type: string
        shifts:
          type: array
          description: Shifts offered for the job.
          items:
            type: string
        schedules:
          type: array
          description: Schedules offered for the job.
          items:
            type: string
        benefits:
          type: array
          description: Benefits offered with the job.
          items:
            type: string
        salary:
          type: object
          description: Salary offered for the job.
          properties:
            min:
              type: number
              description: Lower bound of the salary.
            max:
              type: number
              description: Upper bound of the salary.
            period:
              type: string
              description: Period the salary is paid over.
            currency:
              type: string
              description: Currency of the salary.
            text:
              type: string
              description: Salary as shown on Indeed.
        date:
          type: string
          description: Date the job was posted, as YYYY-MM-DD.
        posted_at:
          type: string
          description: Relative time since the job was posted.
        is_sponsored:
          type: boolean
          description: Whether the job is a sponsored listing.
        description:
          type: string
          description: Snippet of the job description.
        apply_link:
          type: string
          description: Link to apply for the job.
        link:
          type: string
          description: Link to the job posting on Indeed.
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong