> ## Documentation Index
> Fetch the complete documentation index at: https://developers.partoo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Review metrics

> **⚠️ This feature is available only for businesses subscribed to Review Management. ⚠️**

All the operations to perform Reviews analytics.

This endpoint lets you view the statistics related to reviews made to your businesses subscribed to
**Review Management**.

A request is composed of:
- One or more `metrics` which is the data you want to return
- An optional `dimensions` which defines how the data is grouped by
  - If it is omitted, the request will return the metrics over all the data, based on your filters
- An optional `order_by` to define how the data is sorted
- Filters, the data can be filtered by:
  - Businesses
  - Groups
  - Tags
  - Review update date

Here is the list of all **metrics** available:
- `average_rating`: Average rating
- `rating_distribution`: Breakdown of the ratings (Number of 1-star reviews, 2-star reviews, 3-star reviews, etc...)
- `reviews_count`: Number of reviews received
- `reply_time`: Breakdown of the reviews based on how fast (less or more than 48 hours) they have been replied to (or not replied)
- `reply_means`: Breakdown of the review replies based on the reply method used (manual reply, reply template, auto reply or AI suggestion)
- `average_rating_distribution`: Breakdown of your businesses based on their average rating
- `rank`: Allows you to rank the users, businesses or groups based on their performance on a metric (an order_by is required)

Here is the list of all **dimensions** available, and for each of them, the list of metrics and sort order available:
- No dimension
  - This allows you to get global stats across all your businesses
  - Available metrics: `average_rating`, `rating_distribution`, `reviews_count`, `reply_time`, `reply_means`, `average_rating_distribution`
- Date dimensions: `day`, `week`, `month`, `year`
  - This allows you to get the evolution of your metrics over time
  - Available metrics: `average_rating`, `rating_distribution`, `reviews_count`, `reply_time`, `reply_means`
- Business and business group dimensions: `business`, `group`
  - This allows you to see the metrics business by business or group by group (Requires group filter)
  - Available metrics: `average_rating`, `rating_distribution`, `reviews_count`, `reply_time`, `reply_means`, `rank`
- `user`
  - This allows you to see the metrics user by user
  - Available metrics: `reply_time`, `reply_means`, `rank`
- `tag`
  - This allows you to see the metrics tag by tag
  - Available metrics: `average_rating`, `rating_distribution`, `reviews_count`

Here is the list of all **order_by** available (Add a minus `-` sign before to order by decreasing order):
- `average_rating`: Sort by average rating
- `reviews_count`: Sort by review_count
- `reply_time__total`: Sort by number of reviews received
- `reply_means__total`: Sort by number of reviews that have been replied
- `ratio__rating_distribution__5`: Sort by the ratio of 5 star reviews
- `ratio__rating_distribution__negative`: Sort by the ratio of negative reviews
- `ratio__reply_time__fast`: Sort by the ratio of reviews replied in less than 2 days
- `ratio__reply_time__slow`: Sort by the ratio of reviews replied in more than 2 days
- `ratio__reply_time__not_replied`: Sort by the ratio of reviews not replied
- `ratio__reply_means__manual`: Sort by the ratio reviews replied manually
- `ratio__reply_means__ai_suggestion`: Sort by the ratio reviews replied using AI suggestion
- `ratio__reply_means__reply_template`: Sort by the ratio reviews replied using reply template
- `ratio__reply_means__auto_reply`: Sort by the ratio reviews replied using auto reply

To use an **order_by** parameter, its corresponding metric must be included in the request.
(i.e.
to order by `average_rating`, you must include the `average_rating` metric in the `metrics` parameter,
to order by `ratio__rating_distribution__5`, you must include the `rating_distribution` metric in the `metrics` parameter,
and so on...)




## OpenAPI

````yaml /assets/openapi/openapi-bundled.yaml get /review_analytics/metrics
openapi: 3.1.0
info:
  title: Partoo Rest API
  version: v2
  license:
    name: © Copyright Partoo
    url: https://www.partoo.co/en/gtu-api/
  x-logo:
    url: >-
      https://partoo-client-images.s3.amazonaws.com/logo-partoo-restapi-white.png
  description: >
    ## Introduction

    The Partoo Rest API allows you to automate all the actions that are possible
    to do in the Partoo Web Application.


    The Partoo Rest API can be used for many different purposes:
      - Create/update/delete your businesses & users if you are a client.
      - Create/subscribe/manage organizations, businesses & users if you are a reseller.
      - Retrieve data on businesses you have access to if you are a publisher.
      - ...
servers:
  - url: https://api.partoo.co/v2
    description: Production server
  - url: https://api.sandbox.partoo.co/v2
    description: Sandbox server (dev environment for clients & partners)
security:
  - ApiKeyAuth: []
paths:
  /review_analytics/metrics:
    get:
      tags:
        - Review analytics
      summary: Get Review metrics
      description: >
        **⚠️ This feature is available only for businesses subscribed to Review
        Management. ⚠️**


        All the operations to perform Reviews analytics.


        This endpoint lets you view the statistics related to reviews made to
        your businesses subscribed to

        **Review Management**.


        A request is composed of:

        - One or more `metrics` which is the data you want to return

        - An optional `dimensions` which defines how the data is grouped by
          - If it is omitted, the request will return the metrics over all the data, based on your filters
        - An optional `order_by` to define how the data is sorted

        - Filters, the data can be filtered by:
          - Businesses
          - Groups
          - Tags
          - Review update date

        Here is the list of all **metrics** available:

        - `average_rating`: Average rating

        - `rating_distribution`: Breakdown of the ratings (Number of 1-star
        reviews, 2-star reviews, 3-star reviews, etc...)

        - `reviews_count`: Number of reviews received

        - `reply_time`: Breakdown of the reviews based on how fast (less or more
        than 48 hours) they have been replied to (or not replied)

        - `reply_means`: Breakdown of the review replies based on the reply
        method used (manual reply, reply template, auto reply or AI suggestion)

        - `average_rating_distribution`: Breakdown of your businesses based on
        their average rating

        - `rank`: Allows you to rank the users, businesses or groups based on
        their performance on a metric (an order_by is required)


        Here is the list of all **dimensions** available, and for each of them,
        the list of metrics and sort order available:

        - No dimension
          - This allows you to get global stats across all your businesses
          - Available metrics: `average_rating`, `rating_distribution`, `reviews_count`, `reply_time`, `reply_means`, `average_rating_distribution`
        - Date dimensions: `day`, `week`, `month`, `year`
          - This allows you to get the evolution of your metrics over time
          - Available metrics: `average_rating`, `rating_distribution`, `reviews_count`, `reply_time`, `reply_means`
        - Business and business group dimensions: `business`, `group`
          - This allows you to see the metrics business by business or group by group (Requires group filter)
          - Available metrics: `average_rating`, `rating_distribution`, `reviews_count`, `reply_time`, `reply_means`, `rank`
        - `user`
          - This allows you to see the metrics user by user
          - Available metrics: `reply_time`, `reply_means`, `rank`
        - `tag`
          - This allows you to see the metrics tag by tag
          - Available metrics: `average_rating`, `rating_distribution`, `reviews_count`

        Here is the list of all **order_by** available (Add a minus `-` sign
        before to order by decreasing order):

        - `average_rating`: Sort by average rating

        - `reviews_count`: Sort by review_count

        - `reply_time__total`: Sort by number of reviews received

        - `reply_means__total`: Sort by number of reviews that have been replied

        - `ratio__rating_distribution__5`: Sort by the ratio of 5 star reviews

        - `ratio__rating_distribution__negative`: Sort by the ratio of negative
        reviews

        - `ratio__reply_time__fast`: Sort by the ratio of reviews replied in
        less than 2 days

        - `ratio__reply_time__slow`: Sort by the ratio of reviews replied in
        more than 2 days

        - `ratio__reply_time__not_replied`: Sort by the ratio of reviews not
        replied

        - `ratio__reply_means__manual`: Sort by the ratio reviews replied
        manually

        - `ratio__reply_means__ai_suggestion`: Sort by the ratio reviews replied
        using AI suggestion

        - `ratio__reply_means__reply_template`: Sort by the ratio reviews
        replied using reply template

        - `ratio__reply_means__auto_reply`: Sort by the ratio reviews replied
        using auto reply


        To use an **order_by** parameter, its corresponding metric must be
        included in the request.

        (i.e.

        to order by `average_rating`, you must include the `average_rating`
        metric in the `metrics` parameter,

        to order by `ratio__rating_distribution__5`, you must include the
        `rating_distribution` metric in the `metrics` parameter,

        and so on...)
      operationId: getReviewAnalyticsMetrics
      parameters:
        - $ref: '#/components/parameters/query_metrics_reviews'
        - $ref: '#/components/parameters/query_dimensions_reviews'
        - $ref: '#/components/parameters/query_order_by_reviews'
        - $ref: '#/components/parameters/ra_query_business__in'
        - $ref: '#/components/parameters/ra_query_business__notin'
        - $ref: '#/components/parameters/ra_query_groups'
        - $ref: '#/components/parameters/query_tags'
        - $ref: '#/components/parameters/query_update_date__gte'
        - $ref: '#/components/parameters/query_update_date__lte'
        - $ref: '#/components/parameters/ra_query_page'
        - $ref: '#/components/parameters/ra_query_per_page'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ListResult'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/ReviewMetricsResponse'
              examples:
                '?metrics=average_rating&dimensions=business':
                  value:
                    page: 1
                    count: 2
                    max_page: 1
                    data:
                      - dimension: 59b2645db12ff60643ef832c
                        dimension_name: Business 1
                        dimension_info:
                          address_full: 190 rue Championnet
                          city: Paris
                          zipcode: '75018'
                          code: PTOCODE1
                        metrics:
                          average_rating: 2.31
                      - dimension: 60b2645fb12ff60643ef8344
                        dimension_name: Business 2
                        dimension_info:
                          address_full: 190 rue Championnet
                          city: Paris
                          zipcode: '75018'
                          code: PTOCODE2
                        metrics:
                          average_rating: 4.31
                '?metrics=average_rating_distribution':
                  value:
                    page: 1
                    count: 1
                    max_page: 1
                    data:
                      - dimension: null
                        metrics:
                          average_rating_distribution:
                            4.3-5: 274
                            3.8-4.3: 124
                            3-3.8: 62
                            0-3: 5
                            'NULL': 4
                '?metrics=average_rating,reviews_count&dimensions=day&filter_date__lte=2024-02-13&filter_date__gte=2024-02-11':
                  value:
                    page: 1
                    count: 3
                    max_page: 1
                    data:
                      - dimension: '2024-02-11'
                        metrics:
                          average_rating: 3.31
                          reviews_count: 123
                      - dimension: '2024-02-12'
                        metrics:
                          average_rating: 3.34
                          reviews_count: 123
                      - dimension: '2024-02-13'
                        metrics:
                          average_rating: 3.77
                          reviews_count: 123
                '?metrics=reply_time,reply_means&dimensions=user':
                  value:
                    page: 1
                    count: 1
                    max_page: 1
                    data:
                      - dimension: 64477ae0264810a01c0a4edf
                        dimension_name: User 1
                        metrics:
                          reply_time:
                            fast: 11
                            slow: 32
                            not_replied: 0
                            total: 43
                          reply_means:
                            ai_suggestion: 20
                            manual: 3
                            auto_reply: 0
                            reply_template: 20
                            total: 43
                '?metrics=rank,rating_distribution&dimensions=group&order_by=-ratio__rating_distribution__5&groups=1244,1245,1246':
                  value:
                    page: 1
                    count: 3
                    max_page: 1
                    data:
                      - dimension: 1244
                        dimension_name: Group 1244
                        metrics:
                          rank: 1
                          rating_distribution:
                            '1': 0
                            '2': 0
                            '3': 0
                            '4': 0
                            '5': 65
                      - dimension: 1245
                        dimension_name: Group 1245
                        metrics:
                          rank: 1
                          rating_distribution:
                            '1': 0
                            '2': 0
                            '3': 11
                            '4': 32
                            '5': 65
                      - dimension: 60b2645fb12ff60643ef8344
                        dimension_name: Group 1246
                        metrics:
                          rank: 3
                          rating_distribution:
                            '1': 19
                            '2': 0
                            '3': 0
                            '4': 0
                            '5': 0
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
components:
  parameters:
    query_metrics_reviews:
      in: query
      name: metrics
      required: true
      description: |
        List of analytics to return.
         At least one in that list.
      schema:
        type: string
        enum:
          - average_rating
          - rating_distribution
          - reviews_count
          - reply_time
          - reply_means
          - average_rating_distribution
          - rank
    query_dimensions_reviews:
      in: query
      name: dimensions
      required: false
      description: >
        How the returned data will be aggregated.

        If no dimension is given, the request will return the sum of each metric
        for all requested days and businesses.
      schema:
        type: string
        enum:
          - day
          - week
          - month
          - year
          - business
          - group
          - user
          - tag
    query_order_by_reviews:
      in: query
      name: order_by
      required: false
      description: |
        See above for the list of all orders available. At most one in the list.
         - `-` before a field to order_by DESC, nothing for ASC
      schema:
        type: string
        example: '-average_rating'
    ra_query_business__in:
      in: query
      name: business__in
      description: Filter by business ids
      required: false
      schema:
        type: array
        items:
          $ref: '#/components/schemas/BusinessID'
    ra_query_business__notin:
      in: query
      name: business__notin
      required: false
      description: >
        Filter by all allowed businesses except the ones given in
        `business__notin`
      schema:
        type: array
        items:
          $ref: '#/components/schemas/BusinessID'
    ra_query_groups:
      in: query
      name: groups
      description: Filter by groups ids
      required: false
      schema:
        type: array
        items:
          $ref: '#/components/schemas/GroupID'
    query_tags:
      in: query
      name: tags
      description: >
        Restrict the data returned on reviews that have been assigned the
        specified tags.
      schema:
        type: array
        items:
          $ref: '#/components/schemas/TagID'
    query_update_date__gte:
      in: query
      name: update_date__gte
      required: false
      description: >
        Restrict the data returned on reviews which `update_date` are after the
        given date.
      schema:
        type: string
        format: datetime
    query_update_date__lte:
      in: query
      name: update_date__lte
      description: >
        Restrict the data returned on reviews which `update_date` are before the
        given date.
      schema:
        type: string
        format: datetime
    ra_query_page:
      in: query
      name: page
      required: false
      description: |
        The page number you want to request.
      schema:
        type: integer
        default: 1
        minimum: 1
    ra_query_per_page:
      in: query
      name: per_page
      required: false
      description: |
        The maximum number of result items to return in a page.
      schema:
        type: integer
        default: 30
  schemas:
    ListResult:
      type: object
      properties:
        page:
          $ref: '#/components/schemas/current_page'
        max_page:
          $ref: '#/components/schemas/max_page'
        count:
          $ref: '#/components/schemas/count'
    ReviewMetricsResponse:
      type: object
      required:
        - dimension
        - metrics
      properties:
        dimension:
          oneOf:
            - type: string
            - type: number
            - type: 'null'
          description: >
            Unique identifier of the dimension:

            - **string** when `dimensions` is `business`, `user`, `day`, `week`,
            `month`, `year`.

            - **number** when `dimensions` is `group` or `tag`.

            - **null** when `dimensions` is not set.


            When `dimensions` is `day` or `week`, the format is `YYYY-MM-DD`

            When `dimensions` is `month`, the format is `YYYY-MM`

            When `dimensions` is `year`, the format is `YYYY`
          example: 59b2645db12ff60643ef832c
        metrics:
          type: object
          properties:
            average_rating:
              type: number
              format: float
              description: Average rating.
            average_rating_distribution:
              type: object
              description: |
                Number of businesses within each pre-defined ratings.
              properties:
                'NULL':
                  type: number
                  format: integer
                  description: Number of businesses without any average rating.
                0-3:
                  type: number
                  format: integer
                  description: >-
                    Number of businesses whose rating is between 0 and 3
                    (excluded).
                3-3.8:
                  type: number
                  format: integer
                  description: >-
                    Number of businesses whose rating is between 3 (included)
                    and 3.8 (excluded).
                3.8-4.3:
                  type: number
                  format: integer
                  description: >-
                    Number of businesses whose rating is between 3.8 (included)
                    and 4.3 (excluded).
                4.3-5:
                  type: number
                  format: integer
                  description: >-
                    Number of businesses whose rating is between 4.3 (included)
                    and 5.
            rank:
              type: number
              format: integer
              description: >
                Rank of the dimension compared to the others, based on the
                specified `order_by` parameter.


                **Note:** Two results with the same metrics value will have the
                same rank.
            rating_distribution:
              type: object
              properties:
                '1':
                  type: number
                  format: integer
                  description: Number of 1 star reviews.
                '2':
                  type: number
                  format: integer
                  description: Number of 2 star reviews.
                '3':
                  type: number
                  format: integer
                  description: Number of 3 star reviews.
                '4':
                  type: number
                  format: integer
                  description: Number of 4 star reviews.
                '5':
                  type: number
                  format: integer
                  description: Number of 5 star reviews.
            reply_means:
              type: object
              properties:
                ai_suggestion:
                  type: number
                  format: integer
                  description: Number of reviews replied using an AI suggestion.
                auto_reply:
                  type: number
                  format: integer
                  description: Number of reviews replied using the auto reply.
                manual:
                  type: number
                  format: integer
                  description: >-
                    Number of reviews replied manually (without an AI suggestion
                    nor a reply template).
                reply_template:
                  type: number
                  format: integer
                  description: >-
                    Number of reviews replied using a reply template (excluding
                    auto replies).
                total:
                  type: number
                  format: integer
                  description: >-
                    Total (ai_suggestion + auto_reply + manual +
                    reply_template).
            reply_time:
              type: object
              properties:
                fast:
                  type: number
                  format: integer
                  description: Number of reviews replied in less than 2 days
                slow:
                  type: number
                  format: integer
                  description: Number of reviews replied in more than 2 days
                not_replied:
                  type: number
                  format: integer
                  description: Number of reviews not replied
                total:
                  type: number
                  format: integer
                  description: Total (fast + slow + not_replied)
            reviews_count:
              type: number
              format: integer
              description: Number of reviews
        dimension_name:
          type: string
          description: |
            Name of the dimension:
            - Business name when `dimensions` is `business`
            - Group name when `dimensions` is `group`
            - Tag name when `dimensions` is `tag`
            - User full name when `dimensions` is `user`
            - Not present in the response otherwise
        dimension_info:
          type: object
          description: |
            Additional info about the dimension.

            Only returned when `dimensions` is `business`.
          properties:
            address_full:
              $ref: '#/components/schemas/AddressFull'
            city:
              $ref: '#/components/schemas/BusinessCity'
            code:
              $ref: '#/components/schemas/BusinessCode'
            zipcode:
              $ref: '#/components/schemas/BusinessZipcode'
    BusinessID:
      description: Business id
      type: string
      example: 5409c35a97bbc544d8e26737
    GroupID:
      description: Group id
      type: integer
      example: 12312
    TagID:
      description: Tag id
      type: integer
      example: 10,12,44
    current_page:
      type: integer
      description: Current page number
      example: 1
    max_page:
      type: integer
      description: Last page number
      example: 10
    count:
      type: integer
      description: Number of resources complying with filters
      example: 287
    AddressFull:
      description: |
        Full address of the business.

        For example : `130 Rue du Mont-Cenis`.
      type:
        - string
        - 'null'
      example: 12 bis rue du coquelicot
    BusinessCity:
      description: The city where the business is located
      type:
        - string
        - 'null'
      example: Paris
    BusinessCode:
      description: >-
        The unique store code of the business. If not provided, it will be
        automatically generated
      type: string
      example: CS-75019
    BusinessZipcode:
      description: >-
        Zipcode (or postal code) for the business address. Can be empty if the
        business' country does not require one.
      type:
        - string
        - 'null'
      example: '75019'
  responses:
    '400':
      description: Your request is incorrect
      content:
        application/json:
          schema:
            description: |
              Error that occcurs when your request is incorrect
            properties:
              errors:
                type: object
                description: The detail of the error encountered
                properties:
                  json:
                    type: object
    '401':
      description: You are not authenticated
      content:
        application/json:
          schema:
            description: Error that occurs when you are not authenticated
            type: object
            properties:
              errors:
                type: object
                description: The detail of the error encountered
                properties:
                  authentication:
                    type: string
                    default: User not authenticated
    '403':
      description: |
        You are not allowed to perform this action
      content:
        application/json:
          schema:
            description: >
              Error that occurs when you are authenticated but you are trying to
              perform an action you are not allowed to perform
            type: object
            properties:
              errors:
                type: object
                description: The detail of the error encountered
                properties:
                  authorization:
                    type: string
                    default: Operation not allowed
  securitySchemes:
    ApiKeyAuth:
      description: >
        The authentication system on Partoo API is using API Key that should be
        put in the header of the request (the name of the header is `x-APIKey`).
        An api_key is linked to a user. This user's role will give you different
        access level to the API features.
      type: apiKey
      in: header
      name: x-APIKey

````