openapi: 3.0.0
info:
  title: Steam Reviews API
  description: |
    The Steam Reviews API returns user reviews of a Steam app, with each review's text, recommendation, votes, language, dates, playtime and author, and the app's review summary.

    By default it returns the most helpful English reviews of the last 365 days, from every purchase type. Reviews from periods Steam marks as off-topic review activity are left out, as on its store page.

    The review summary in `product` counts the reviews that match the filters. Steam sends it on the first page only, and not with `review_type`.

    To get the next page, pass `pagination.next_page_token` with the same `app_id`. The token carries the filters, sort and page size of the request that returned it.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Steam Reviews Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Engine to use for the search
          schema:
            type: string
            enum: ["steam_reviews"]
            default: "steam_reviews"
        - name: app_id
          in: query
          required: true
          description: Steam app ID, the number in the app's store page URL, such as 588650, from 1 to 4294967295
          schema:
            type: string
            pattern: '^[1-9]\d{0,9}$'
        - name: hl
          in: query
          required: false
          description: Language of the reviews, or all for reviews in every language
          schema:
            type: string
            enum: ["ar", "bg", "zh-cn", "zh-tw", "cs", "da", "nl", "en", "fi", "fr", "de", "el", "hu", "id", "it", "ja", "ko", "ms", "no", "pl", "pt", "pt-br", "ro", "ru", "es", "es-419", "sv", "th", "tr", "uk", "vi", "all"]
            default: "en"
        - name: review_type
          in: query
          required: false
          description: Recommendation of the reviews to return. With positive or negative, the response has no review summary in product.
          schema:
            type: string
            enum: ["positive", "negative", "all"]
            default: "all"
        - name: purchase_type
          in: query
          required: false
          description: How the authors got the app. steam returns reviews by people who bought it on Steam, and non_steam the rest.
          schema:
            type: string
            enum: ["steam", "non_steam", "all"]
            default: "all"
        - name: time_period_min
          in: query
          required: false
          description: First day of the time period the reviews were written in, in UTC, as YYYY-MM-DD or MM/DD/YYYY, from 1970 to 2099
          schema:
            type: string
            pattern: '^((19[7-9]\d|20\d\d)-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])|(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01])/(19[7-9]\d|20\d\d))$'
        - name: time_period_max
          in: query
          required: false
          description: Last day of the time period the reviews were written in, in UTC, as YYYY-MM-DD or MM/DD/YYYY. It must not be before time_period_min.
          schema:
            type: string
            pattern: '^((19[7-9]\d|20\d\d)-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])|(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01])/(19[7-9]\d|20\d\d))$'
        - name: playtime_min
          in: query
          required: false
          description: Fewest hours the author had played the app when writing the review
          schema:
            type: integer
            minimum: 1
            maximum: 35791394
        - name: playtime_max
          in: query
          required: false
          description: Most hours the author had played the app when writing the review. It must not be below playtime_min.
          schema:
            type: integer
            minimum: 1
            maximum: 35791394
        - name: is_primarily_steam_deck
          in: query
          required: false
          description: Set to true to return only reviews whose author played the app mostly on Steam Deck
          schema:
            type: boolean
        - name: sort_by
          in: query
          required: false
          description: Order of the reviews. most_helpful ranks the reviews written in the last day_range days by how helpful readers found them. With a time period, it ranks the reviews of that period instead. A period that starts more than a year ago and has not ended or ended in the last 180 days is ranked over its last year only, so use most_recent to get all of it.
          schema:
            type: string
            enum: ["most_helpful", "most_recent", "recently_updated", "funniest"]
            default: "most_helpful"
        - name: day_range
          in: query
          required: false
          description: Number of days back most_helpful looks for reviews. When those days hold no reviews, Steam looks further back, up to all of the app's reviews. It works only with sort_by=most_helpful, and has no effect with time_period_min or time_period_max.
          schema:
            type: integer
            minimum: 1
            maximum: 365
            default: 365
        - name: num
          in: query
          required: false
          description: Number of reviews per page
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: next_page_token
          in: query
          required: false
          description: Token for the next page, from pagination.next_page_token of the previous response. It carries that request's filters, sort and page size.
          schema:
            type: string
            maxLength: 1024
      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'
        search_information:
          $ref: '#/components/schemas/SearchInformation'
        product:
          $ref: '#/components/schemas/Product'
        reviews:
          type: array
          description: The reviews on the current page
          items:
            $ref: '#/components/schemas/Review'
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Message explaining why the response has no reviews
    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: Steam store page URL of the app
        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: Engine used for the search
        app_id:
          type: string
          description: Steam app ID searched for
        sort_by:
          type: string
          description: Sort order applied
        hl:
          type: string
          description: Review language applied
        review_type:
          type: string
          description: Recommendation filter applied
        purchase_type:
          type: string
          description: Purchase type filter applied
        time_period_min:
          type: string
          description: First day of the time period applied
        time_period_max:
          type: string
          description: Last day of the time period applied
        day_range:
          type: string
          description: Day window of the most helpful sort applied
        playtime_min:
          type: string
          description: Fewest hours of playtime applied
        playtime_max:
          type: string
          description: Most hours of playtime applied
        is_primarily_steam_deck:
          type: string
          description: Steam Deck filter applied
        num:
          type: string
          description: Number of reviews per page requested
        next_page_token:
          type: string
          description: Token of the page requested
    SearchInformation:
      type: object
      properties:
        total_results:
          type: integer
          description: Number of reviews in the list the sort and filters select
    Product:
      type: object
      description: The app and its review summary
      required: [app_id, link]
      properties:
        app_id:
          type: integer
          description: Steam app ID
        link:
          type: string
          description: Steam store page of the app
        rating_label:
          type: string
          description: Steam's review score label for the matching reviews, such as Overwhelmingly Positive
        reviews:
          type: integer
          description: Number of reviews matching the filters
        positive_reviews:
          type: integer
          description: Number of matching reviews that recommend the app
        negative_reviews:
          type: integer
          description: Number of matching reviews that do not recommend the app
        recommended_percentage:
          type: integer
          description: Share of matching reviews that recommend the app, in whole percent rounded down
    Review:
      type: object
      required: [position, review_id]
      properties:
        position:
          type: integer
          description: Position of the review in the list, counted on from earlier pages
        review_id:
          type: string
          description: Steam ID of the review
        link:
          type: string
          description: Page of the review on Steam Community
        text:
          type: string
          description: Review text with Steam's formatting tags as the author wrote them
        is_recommended:
          type: boolean
          description: Whether the author recommends the app
        language:
          type: string
          description: Language code of the review
        iso_date:
          type: string
          format: date-time
          description: Time the review was posted
        iso_last_updated:
          type: string
          format: date-time
          description: Time the review was last edited
        helpful_votes:
          type: integer
          description: Number of readers who found the review helpful
        funny_votes:
          type: integer
          description: Number of readers who found the review funny
        weighted_vote_score:
          type: number
          description: Steam's helpfulness score of the review, from 0 to 1
        comments:
          type: integer
          description: Number of comments on the review
        awards:
          type: array
          description: Awards readers gave the review with Steam Points
          items:
            $ref: '#/components/schemas/Award'
        is_steam_purchase:
          type: boolean
          description: Whether the author bought the app on Steam
        is_received_for_free:
          type: boolean
          description: Whether the author got the app for free
        is_written_during_early_access:
          type: boolean
          description: Whether the review was written while the app was in early access
        is_primarily_steam_deck:
          type: boolean
          description: Whether the author played the app mostly on Steam Deck when writing the review
        is_refunded:
          type: boolean
          description: Whether the author refunded the app
        user:
          $ref: '#/components/schemas/User'
        hardware:
          $ref: '#/components/schemas/Hardware'
        response:
          $ref: '#/components/schemas/Response'
    Award:
      type: object
      description: An award readers gave the review
      required: [count, thumbnail]
      properties:
        title:
          type: string
          description: Name of the award
        count:
          type: integer
          description: Number of readers who gave the award
        thumbnail:
          type: string
          description: Image of the award
    User:
      type: object
      description: The author of the review
      properties:
        steam_id:
          type: string
          description: Steam ID of the author
        name:
          type: string
          description: Display name of the author
        link:
          type: string
          description: Profile page of the author on Steam Community
        thumbnail:
          type: string
          description: Profile picture of the author
        games_owned:
          type: integer
          description: Number of games the author owns
        reviews:
          type: integer
          description: Number of reviews the author has written
        iso_last_played:
          type: string
          format: date-time
          description: Time the author last played the app
        playtime:
          $ref: '#/components/schemas/Playtime'
    Playtime:
      type: object
      description: The author's time in the app, in minutes
      properties:
        total_minutes:
          type: integer
          description: Minutes the author has played the app
        last_two_weeks_minutes:
          type: integer
          description: Minutes the author played the app in the last two weeks
        at_review_minutes:
          type: integer
          description: Minutes the author had played the app when writing the review
        steam_deck_at_review_minutes:
          type: integer
          description: Minutes the author had played the app on Steam Deck when writing the review
    Hardware:
      type: object
      description: The computer the author chose to show with the review
      properties:
        os:
          type: string
          description: Operating system
        cpu:
          type: string
          description: Processor
        gpu:
          type: string
          description: Graphics card
        ram_mb:
          type: integer
          description: Memory in megabytes
        vram_mb:
          type: integer
          description: Video memory in megabytes
    Response:
      type: object
      description: The developer's reply to the review
      required: [text]
      properties:
        text:
          type: string
          description: Text of the reply
        iso_date:
          type: string
          format: date-time
          description: Time the developer replied
    Pagination:
      type: object
      required: [next_page_token]
      properties:
        next_page_token:
          type: string
          description: Token for the next page of reviews, to pass as next_page_token
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
