openapi: 3.0.0
info:
  title: Indeed Salaries API
  description: |
    Get salaries for a job title on Indeed, nationally or in a location.

    The response returns the median, low and high pay for each pay period with the number of salaries behind them, the most common pay period and bonuses, plus national figures when a location is given. It also lists the top-paying companies, the top-paying cities, related job titles and the skills or qualifications that raise pay. Use `gl` to read a country's Indeed site.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Indeed Salaries Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: 'Search engine. Must be set to: `indeed_salaries`'
          schema:
            type: string
            enum: ["indeed_salaries"]
        - name: q
          in: query
          required: true
          description: Job title, in the language of the country's Indeed site, such as `registered nurse` or `softwareentwickler`.
          schema:
            type: string
            maxLength: 200
        - name: location
          in: query
          required: false
          description: City and state such as `Chicago, IL`, a state such as `California`, or a city such as `Toronto, ON`. Omit it for national figures.
          schema:
            type: string
            maxLength: 200
            pattern: '[^,\s]'
        - name: gl
          in: query
          required: false
          description: Country whose Indeed site to read, as an ISO 3166-1 alpha-2 code.
          schema:
            type: string
            enum: ["us", "ae", "ar", "at", "au", "be", "br", "ca", "ch", "cl", "co", "cz", "de", "eg", "es", "fr", "gb", "gr", "hk", "hu", "ie", "il", "in", "it", "kr", "mx", "my", "nl", "no", "nz", "pe", "ph", "pk", "pl", "pt", "sa", "se", "sg", "tr", "za"]
            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
      required: [search_metadata, search_parameters]
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        error:
          type: string
          description: Why there is no salary data to return.
        search_information:
          type: object
          required: [job_title, location]
          properties:
            job_title:
              type: string
              description: Job title Indeed matched, which can differ from q.
            normalized_title:
              type: string
              description: Indeed's normalized form of the matched job title.
            location:
              type: string
              description: Location the salaries cover.
            country:
              type: string
              description: Country code of the Indeed site.
            last_updated:
              type: string
              description: Date Indeed last updated the salary figures.
        salary:
          $ref: '#/components/schemas/Salary'
        national_salary:
          $ref: '#/components/schemas/Salary'
        salary_impact:
          type: array
          description: Skills and qualifications associated with higher or lower pay for this job title.
          items:
            type: object
            required: [name, average_impact]
            properties:
              name:
                type: string
                description: Name of the skill or qualification.
              dimension:
                type: string
                description: Kind of attribute, such as skill or fields_of_study.
              category:
                type: string
                description: Display name of the attribute's kind.
              average_impact:
                type: number
                description: Average change in pay associated with the attribute, as a fraction.
              min_impact:
                type: number
                description: Lowest change in pay associated with the attribute, as a fraction.
              max_impact:
                type: number
                description: Highest change in pay associated with the attribute, as a fraction.
              job_openings:
                type: integer
                description: Number of job openings Indeed counts for the attribute.
              companies:
                type: integer
                description: Number of companies Indeed counts for the attribute.
        top_paying_cities:
          type: array
          description: Cities where this job title pays the most.
          items:
            type: object
            required: [location, median]
            properties:
              location:
                type: string
                description: Name of the city.
              median:
                type: number
                description: Typical pay in the city for its most common pay period.
              period:
                type: string
                description: Pay period of the median.
              currency:
                type: string
                description: Currency code of the median.
              link:
                type: string
                description: URL of the job title's salaries in the city on Indeed.
        top_paying_companies:
          type: array
          description: Companies that pay the most for this job title.
          items:
            type: object
            required: [name]
            properties:
              name:
                type: string
                description: Name of the company.
              company_id:
                type: string
                description: Indeed company identifier, usable as company_id in the indeed_company_reviews engine.
              link:
                type: string
                description: URL of the company's Indeed page.
              rating:
                type: number
                description: Overall employee rating of the company, from 1 to 5.
              reviews_count:
                type: integer
                description: Number of employee reviews of the company.
              average_salary:
                type: number
                description: Average pay for this job title at the company, from job postings on Indeed.
              salary_period:
                type: string
                description: Pay period of the average salary.
              salary_reports:
                type: integer
                description: Number of salary reports behind the average.
        related_titles:
          type: array
          description: Related job titles and their pay.
          items:
            type: object
            required: [title]
            properties:
              title:
                type: string
                description: Related job title.
              average_salary:
                type: number
                description: Average pay for the related job title.
              salary_period:
                type: string
                description: Pay period of the average salary.
              link:
                type: string
                description: URL of the related job title's salaries on Indeed.
    Salary:
      type: object
      required: [currency, most_common_period, periods]
      properties:
        currency:
          type: string
          description: Currency code of the pay figures.
        most_common_period:
          type: string
          description: Pay period most salaries for this job title are quoted in.
          enum: ["hourly", "daily", "weekly", "monthly", "yearly"]
        periods:
          type: object
          description: Pay figures for each pay period.
          properties:
            hourly:
              $ref: '#/components/schemas/PayFigures'
            daily:
              $ref: '#/components/schemas/PayFigures'
            weekly:
              $ref: '#/components/schemas/PayFigures'
            monthly:
              $ref: '#/components/schemas/PayFigures'
            yearly:
              $ref: '#/components/schemas/PayFigures'
        bonuses:
          type: array
          description: Extra pay on top of the salary, such as bonuses or overtime.
          items:
            type: object
            properties:
              type:
                type: string
                description: Kind of bonus, such as cash_bonus.
              period:
                type: string
                description: Pay period of the bonus.
              mean:
                type: number
                description: Average bonus amount.
    PayFigures:
      type: object
      required: [median, low, high]
      properties:
        median:
          type: number
          description: Typical pay, which Indeed shows as the average salary.
        low:
          type: number
          description: Low end of the typical pay range.
        high:
          type: number
          description: High end of the typical pay range.
        mean:
          type: number
          description: Mean of the reported pay.
        std_dev:
          type: number
          description: Standard deviation of the reported pay.
        data_points:
          type: integer
          description: Number of salaries the figures are based on, counted on the most common pay period and 0 on the periods Indeed converts from it.
        is_inferred:
          type: boolean
          description: Whether Indeed estimated the figures rather than measuring them.
    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
        q:
          type: string
        location:
          type: string
        gl:
          type: string
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong