Revinate Hotels API

openapi: 3.2.0
info:
  title: Revinate Porter Hotels API
  version: '1.0'
  description: 'Revinate''s structured review data API. Provides access to hotel reviews across 100+ review sites, with key metrics (review counts, average ratings), sentiment analysis, competitor review streams and survey email statistics.


    Two review streams exist and they are not interchangeable: the Review Stream (/reviews, /hotels/{hotelId}/reviews) is for offline analysis and its content may NOT be used for display, while the Widget Review Stream (/widgetreviews) is licensed for display/republishing but excludes TripAdvisor and Yelp content under content-licensing agreements with those partners.


    CONVERSION NOTE: Revinate publishes this contract as Swagger 1.2 at https://porter.revinate.com/api-docs. This OpenAPI 3.1.0 document is a faithful mechanical conversion of the six published Swagger 1.2 resource declarations by API Evangelist; the verbatim originals are preserved in openapi/_original/. Operation IDs were made unique (the published nickname "get" is reused across all six resources).'
  contact:
    name: Revinate Support
    email: support@revinate.com
    url: https://www.revinate.com/support/
  license:
    name: Revinate API License
    url: https://www.revinate.com/website-terms-of-use/
servers:
- url: https://porter.revinate.com
  description: Revinate Porter API production base URL
security:
- porterUsername: []
  porterTimestamp: []
  porterKey: []
  porterEncoded: []
tags:
- name: Hotels
paths:
  /hotels:
    get:
      tags:
      - Hotels
      summary: Get Hotels
      description: Retrieve a list view of all hotels accessible to the API key provided. Pagination is supported by this resource.
      operationId: listHotels
      parameters:
      - name: page
        in: query
        required: false
        description: page number
        schema:
          type: integer
          description: page number
      - name: size
        in: query
        required: false
        description: number of elements to show per page
        schema:
          type: integer
          description: number of elements to show per page
      - name: sort
        in: query
        required: false
        description: sort field and direction (eg. ?sort=name,ASC)
        schema:
          type: string
          description: sort field and direction (eg. ?sort=name,ASC)
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      security:
      - porterUsername: []
        porterTimestamp: []
        porterKey: []
        porterEncoded: []
  /hotels/{hotelId}:
    get:
      tags:
      - Hotels
      summary: Get a Hotel
      description: Retrieve a hotel resource by primary hotel id.
      operationId: getHotel
      parameters:
      - name: hotelId
        in: path
        required: true
        description: identifier of Hotel
        schema:
          type: integer
          format: int64
          description: identifier of Hotel
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      security:
      - porterUsername: []
        porterTimestamp: []
        porterKey: []
        porterEncoded: []
  /hotels/{hotelId}/competitorhotels:
    get:
      tags:
      - Hotels
      summary: Get competitor hotels for a hotel
      description: Retrieve a list of competitor hotels for the hotel with the given hotel id.
      operationId: getCompetitorHotelsByHotelId
      parameters:
      - name: hotelId
        in: path
        required: true
        description: identifier of Hotel
        schema:
          type: integer
          format: int64
          description: identifier of Hotel
      - name: page
        in: query
        required: false
        description: page number
        schema:
          type: integer
          description: page number
      - name: size
        in: query
        required: false
        description: number of elements to show per page
        schema:
          type: integer
          description: number of elements to show per page
      - name: sort
        in: query
        required: false
        description: sort field and direction (eg. ?sort=name,ASC)
        schema:
          type: string
          description: sort field and direction (eg. ?sort=name,ASC)
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      security:
      - porterUsername: []
        porterTimestamp: []
        porterKey: []
        porterEncoded: []
  /hotels/{hotelId}/competitorreviews:
    get:
      tags:
      - Hotels
      summary: Get competitor reviews for a hotel
      description: Retrieve the latest reviews associated with competitor hotels for the hotel identified by hotelId. This endpoint supports pagination and sorting if your API key is configured for it. If not configured, the response will be an error if exceeding the review limit. In addition, this endpoint supports query parameter filtering by competitor hotel slug.
      operationId: getCompetitorReviewsByHotelId
      parameters:
      - name: hotelId
        in: path
        required: true
        description: identifier of Hotel
        schema:
          type: integer
          format: int64
          description: identifier of Hotel
      - name: competitorHotelSlug
        in: query
        required: false
        description: slug of competitor hotel
        schema:
          type: string
          description: slug of competitor hotel
      - name: dateCollected
        in: query
        required: false
        description: Filter reviews using dateCollected field with an epoch seconds date range of format {start}..{end} (eg. 1389402398..1420938399). This query parameter is only available for Revinate customers
        schema:
          type: string
          description: Filter reviews using dateCollected field with an epoch seconds date range of format {start}..{end} (eg. 1389402398..1420938399). This query parameter is only available for Revinate customers
      - name: updatedAt
        in: query
        required: false
        description: Filter reviews using updatedAt field with an epoch seconds date range of format {start}..{end} (eg. 1389402398..1420938399). This query parameter is only available for Revinate customers
        schema:
          type: string
          description: Filter reviews using updatedAt field with an epoch seconds date range of format {start}..{end} (eg. 1389402398..1420938399). This query parameter is only available for Revinate customers
      - name: page
        in: query
        required: false
        description: page number
        schema:
          type: integer
          description: page number
      - name: size
        in: query
        required: false
        description: number of elements to show per page
        schema:
          type: integer
          description: number of elements to show per page
      - name: sort
        in: query
        required: false
        description: sort field and direction (eg. ?sort=rating,desc)
        schema:
          type: string
          description: sort field and direction (eg. ?sort=rating,desc)
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      security:
      - porterUsername: []
        porterTimestamp: []
        porterKey: []
        porterEncoded: []
  /hotels/{hotelId}/hotelsets:
    get:
      tags:
      - Hotels
      summary: Get Hotel sets
      description: Retrieve a list view of all hotel sets for a given Corporate group. Pagination is supported by this resource.
      operationId: getHotelSetsForCorporateHotel
      parameters:
      - name: hotelId
        in: path
        required: true
        description: identifier of Corporate group
        schema:
          type: integer
          format: int64
          description: identifier of Corporate group
      - name: page
        in: query
        required: false
        description: page number
        schema:
          type: integer
          description: page number
      - name: size
        in: query
        required: false
        description: number of elements to show per page
        schema:
          type: integer
          description: number of elements to show per page
      - name: sort
        in: query
        required: false
        description: sort field and direction (eg. ?sort=name,ASC)
        schema:
          type: string
          description: sort field and direction (eg. ?sort=name,ASC)
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      security:
      - porterUsername: []
        porterTimestamp: []
        porterKey: []
        porterEncoded: []
  /hotels/{hotelId}/reviews:
    get:
      tags:
      - Hotels
      summary: Get reviews for a hotel
      description: Retrieve the latest reviews associated with the hotel resource identified by hotelId. This endpoint supports pagination and sorting if your API key is configured for it. If not configured, the response will be an error if exceeding the review limit. In addition, this endpoint supports additional query parameter filters (ratings, feedback, and languageSlug)
      operationId: getReviewsByHotelId
      parameters:
      - name: hotelId
        in: path
        required: true
        description: identifier of Hotel
        schema:
          type: integer
          format: int64
          description: identifier of Hotel
      - name: ratings
        in: query
        required: false
        description: list of ratings (1-5) to filter the results by (eg. rating=4,5)
        schema:
          type: array
          items:
            type: integer
            format: int32
          description: list of ratings (1-5) to filter the results by (eg. rating=4,5)
      - name: feedback
        in: query
        required: false
        description: type of feedback to filter results by. Valid values are [positive, neutral, negative]
        schema:
          type: string
          description: type of feedback to filter results by. Valid values are [positive, neutral, negative]
      - name: response
        in: query
        required: false
        description: response status to filter results by. Valid values are [none, posted]
        schema:
          type: string
          description: response status to filter results by. Valid values are [none, posted]
      - name: languageSlug
        in: query
        required: false
        description: slug of the language to filter results by. Valid values are from the '/languages' endpoint
        schema:
          type: string
          description: slug of the language to filter results by. Valid values are from the '/languages' endpoint
      - name: reviewSiteSlug
        in: query
        required: false
        description: slug of the review site to filter results by. Valid values are from the '/reviewsites' endpoint
        schema:
          type: string
          description: slug of the review site to filter results by. Valid values are from the '/reviewsites' endpoint
      - name: dateCollected
        in: query
        required: false
        description: Filter reviews using dateCollected field with an epoch seconds date range of format {start}..{end} (eg. 1389402398..1420938399). This query parameter is only available for Revinate customers
        schema:
          type: string
          description: Filter reviews using dateCollected field with an epoch seconds date range of format {start}..{end} (eg. 1389402398..1420938399). This query parameter is only available for Revinate customers
      - name: updatedAt
        in: query
        required: false
        description: Filter reviews using updatedAt field with an epoch seconds date range of format {start}..{end} (eg. 1389402398..1420938399). This query parameter is only available for Revinate customers
        schema:
          type: string
          description: Filter reviews using updatedAt field with an epoch seconds date range of format {start}..{end} (eg. 1389402398..1420938399). This query parameter is only available for Revinate customers
      - name: page
        in: query
        required: false
        description: page number
        schema:
          type: integer
          description: page number
      - name: size
        in: query
        required: false
        description: number of elements to show per page
        schema:
          type: integer
          description: number of elements to show per page
      - name: sort
        in: query
        required: false
        description: sort field and direction (eg. ?sort=rating,desc)
        schema:
          type: string
          description: sort field and direction (eg. ?sort=rating,desc)
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      security:
      - porterUsername: []
        porterTimestamp: []
        porterKey: []
        porterEncoded: []
  /hotels/{hotelId}/reviewssnapshot:
    get:
      tags:
      - Hotels
      summary: Get reviews snapshot for a hotel
      description: Retrieve analytic data for the reviews of the hotel identified by hotelId. This resource supports date filtering
      operationId: getReviewsSnapshotByHotelId
      parameters:
      - name: hotelId
        in: path
        required: true
        description: identifier of Hotel
        schema:
          type: integer
          format: int64
          description: identifier of Hotel
      - name: date
        in: query
        required: false
        description: epoch seconds date range of format {start}..{end} (eg. 1389402398..1420938399)
        schema:
          type: string
          description: epoch seconds date range of format {start}..{end} (eg. 1389402398..1420938399)
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      security:
      - porterUsername: []
        porterTimestamp: []
        porterKey: []
        porterEncoded: []
  /hotels/{hotelId}/surveyemailstats:
    get:
      tags:
      - Hotels
      summary: Get survey email statistics for hotel
      description: Retrieve survey email statistics of hotel identified by hotelId. This resource supports date filtering
      operationId: getSurveyEmailStatsByHotelId
      parameters:
      - name: hotelId
        in: path
        required: true
        description: identifier of Hotel
        schema:
          type: integer
          format: int64
          description: identifier of Hotel
      - name: date
        in: query
        required: false
        description: epoch seconds date range of format {start}..{end} (eg. 1389402398..1420938399)
        schema:
          type: string
          description: epoch seconds date range of format {start}..{end} (eg. 1389402398..1420938399)
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      security:
      - porterUsername: []
        porterTimestamp: []
        porterKey: []
        porterEncoded: []
  /hotels/{hotelId}/topiccategoriessnapshot:
    get:
      tags:
      - Hotels
      summary: Get category level sentiment analysis for hotel
      description: Retrieve sentiment analytics data for each parent category of hotel identified by hotelId. This resource supports date filtering.
      operationId: getSentimentSnapshotByHotelId
      parameters:
      - name: hotelId
        in: path
        required: true
        description: identifier of Hotel
        schema:
          type: integer
          format: int64
          description: identifier of Hotel
      - name: date
        in: query
        required: false
        description: epoch seconds date range of format {start}..{end} (eg. 1389402398..1420938399)
        schema:
          type: string
          description: epoch seconds date range of format {start}..{end} (eg. 1389402398..1420938399)
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      security:
      - porterUsername: []
        porterTimestamp: []
        porterKey: []
        porterEncoded: []
  /hotels/{hotelId}/topicssnapshot:
    get:
      tags:
      - Hotels
      summary: Get child level sentiment analysis for hotel
      description: Retrieve sentiment analytics data for each child category of hotel identified by hotelId. This resource supports date filtering. In addition, this resource also supports filtering by the topic category id. By default, the endpoint returns all child entries of the "Overall" category (topicCategoryId = 0) which includes all children.
      operationId: getSentimentBreakdownByHotelIdAndTopicCategoryId
      parameters:
      - name: hotelId
        in: path
        required: true
        description: identifier of Hotel
        schema:
          type: integer
          format: int64
          description: identifier of Hotel
      - name: topicCategoryId
        in: query
        required: false
        description: id of the topic category to filter child categories
        schema:
          type: integer
          format: int32
          description: id of the topic category to filter child categories
      - name: date
        in: query
        required: false
        description: epoch seconds date range of format {start}..{end} (eg. 1389402398..1420938399)
        schema:
          type: string
          description: epoch seconds date range of format {start}..{end} (eg. 1389402398..1420938399)
      - name: reviewSiteSlug
        in: query
        required: false
        description: slug of the review site to filter results by. Valid values are from the '/reviewsites' endpoint
        schema:
          type: string
          description: slug of the review site to filter results by. Valid values are from the '/reviewsites' endpoint
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      security:
      - porterUsername: []
        porterTimestamp: []
        porterKey: []
        porterEncoded: []
  /hotels/{hotelId}/widgetreviews:
    get:
      tags:
      - Hotels
      summary: Get reviews for a hotel suitable for display or republishing
      description: Retrieve the latest reviews associated with the hotel resource identified by hotelId suitable for display or republishing. This endpoint supports pagination and sorting if your API key is configured for it. If not configured, the response will be an error if exceeding the review limit. In addition, this endpoint supports additional query parameter filters (ratings, feedback, and languageSlug)
      operationId: getWidgetReviewsByHotelId
      parameters:
      - name: hotelId
        in: path
        required: true
        description: identifier of Hotel
        schema:
          type: integer
          format: int64
          description: identifier of Hotel
      - name: ratings
        in: query
        required: false
        description: list of ratings (1-5) to filter the results by (eg. rating=4,5)
        schema:
          type: array
          items:
            type: integer
            format: int32
          description: list of ratings (1-5) to filter the results by (eg. rating=4,5)
      - name: feedback
        in: query
        required: false
        description: type of feedback to filter results by. Valid values are [positive, neutral, negative]
        schema:
          type: string
          description: type of feedback to filter results by. Valid values are [positive, neutral, negative]
      - name: response
        in: query
        required: false
        description: response status to filter results by. Valid values are [none, posted]
        schema:
          type: string
          description: response status to filter results by. Valid values are [none, posted]
      - name: languageSlug
        in: query
        required: false
        description: slug of the language to filter results by. Valid values are from the '/languages' endpoint
        schema:
          type: string
          description: slug of the language to filter results by. Valid values are from the '/languages' endpoint
      - name: reviewSiteSlug
        in: query
        required: false
        description: slug of the review site to filter results by. Valid values are from the '/reviewsites' endpoint
        schema:
          type: string
          description: slug of the review site to filter results by. Valid values are from the '/reviewsites' endpoint
      - name: dateCollected
        in: query
        required: false
        description: Filter reviews using dateCollected field with an epoch seconds date range of format {start}..{end} (eg. 1389402398..1420938399). This query parameter is only available for Revinate customers
        schema:
          type: string
          description: Filter reviews using dateCollected field with an epoch seconds date range of format {start}..{end} (eg. 1389402398..1420938399). This query parameter is only available for Revinate customers
      - name: updatedAt
        in: query
        required: false
        description: Filter reviews using updatedAt field with an epoch seconds date range of format {start}..{end} (eg. 1389402398..1420938399). This query parameter is only available for Revinate customers
        schema:
          type: string
          description: Filter reviews using updatedAt field with an epoch seconds date range of format {start}..{end} (eg. 1389402398..1420938399). This query parameter is only available for Revinate customers
      - name: page
        in: query
        required: false
        description: page number
        schema:
          type: integer
          description: page number
      - name: size
        in: query
        required: false
        description: number of elements to show per page
        schema:
          type: integer
          description: number of elements to show per page
      - name: sort
        in: query
        required: false
        description: sort field and direction (eg. ?sort=rating,desc)
        schema:
          type: string
          description: sort field and direction (eg. ?sort=rating,desc)
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      security:
      - porterUsername: []
        porterTimestamp: []
        porterKey: []
        porterEncoded: []
components:
  securitySchemes:
    porterUsername:
      type: apiKey
      in: header
      name: X-Revinate-Porter-Username
      description: Username with access to the requested resources and to the API key used.
    porterTimestamp:
      type: apiKey
      in: header
      name: X-Revinate-Porter-Timestamp
      description: Epoch-seconds timestamp; must be within 5 minutes (before or after) of the request.
    porterKey:
      type: apiKey
      in: header
      name: X-Revinate-Porter-Key
      description: API key issued by Revinate (contact your sales rep or account manager).
    porterEncoded:
      type: apiKey
      in: header
      name: X-Revinate-Porter-Encoded
      description: HMAC_SHA256(apiSecret, username + timestamp), hex-encoded.