> ## 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.

# Profile keywords for your business

> This endpoint lets you view the monthly **Google Business Profile** search keywords for all your businesses subscribed to Presence Management.

To access the analytics of a business, you need to:
- have `READ` access on it
- have subscribed to **Presence Management** for this business.
- You can access the search keywords from **Google Business Profile**.

The analytics on search keywords are made available by Google Business Profile on a monthly basis.

You will receive the following metrics:

- count: The sum of the number of unique users that used the keyword in a month
- threshold: A threshold value indicating that the actual value is less than the threshold. Google Business Profile typically displays for search keywords that were used less than 15 times in a month.

You can use the following filters:

- by businesses (businesses id in list, and restricted to one business when using the keyword dimension.)
- by date (analytics before and/or after a date)
- by branded status (branded vs discovery keywords)

The response can be aggregated by:
- business id
- by date: month or year
- by keyword
- by branded status (branded vs discovery)

The response can be ordered by:

- business id
- by date: month, or year
- by keyword
- by branded status

The response can be ordered in ascending or descending order by any of the selected dimensions or metrics.




## OpenAPI

````yaml /assets/openapi/openapi-bundled.yaml get /presence_analytics/keywords
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:
  /presence_analytics/keywords:
    get:
      tags:
        - Presence analytics
      summary: Profile keywords for your business
      description: >
        This endpoint lets you view the monthly **Google Business Profile**
        search keywords for all your businesses subscribed to Presence
        Management.


        To access the analytics of a business, you need to:

        - have `READ` access on it

        - have subscribed to **Presence Management** for this business.

        - You can access the search keywords from **Google Business Profile**.


        The analytics on search keywords are made available by Google Business
        Profile on a monthly basis.


        You will receive the following metrics:


        - count: The sum of the number of unique users that used the keyword in
        a month

        - threshold: A threshold value indicating that the actual value is less
        than the threshold. Google Business Profile typically displays for
        search keywords that were used less than 15 times in a month.


        You can use the following filters:


        - by businesses (businesses id in list, and restricted to one business
        when using the keyword dimension.)

        - by date (analytics before and/or after a date)

        - by branded status (branded vs discovery keywords)


        The response can be aggregated by:

        - business id

        - by date: month or year

        - by keyword

        - by branded status (branded vs discovery)


        The response can be ordered by:


        - business id

        - by date: month, or year

        - by keyword

        - by branded status


        The response can be ordered in ascending or descending order by any of
        the selected dimensions or metrics.
      operationId: getPresenceAnalyticsKeywords
      parameters:
        - $ref: '#/components/parameters/query_metrics_keywords'
        - $ref: '#/components/parameters/query_dimensions_keywords'
        - $ref: '#/components/parameters/query_order_by_keywords'
        - $ref: '#/components/parameters/pa_keywords_query_business__in'
        - $ref: '#/components/parameters/pa_keywords_query_filter_date__gte'
        - $ref: '#/components/parameters/pa_keywords_query_filter_date__lte'
        - $ref: '#/components/parameters/query_branded'
        - $ref: '#/components/parameters/pa_pagination_query_page'
        - $ref: '#/components/parameters/pa_pagination_query_per_page'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PresenceAnalyticsKeywordsResponse'
              examples:
                dimensions=month,keyword,branded:
                  value:
                    page: 1
                    count: 6
                    max_page: 1
                    keywords:
                      - branded: discovery
                        bucket: month
                        date: '2022-03-01'
                        keyword: bar
                        threshold: 42
                      - branded: branded
                        bucket: month
                        count: 9001
                        date: '2022-03-01'
                        keyword: foo
                      - branded: discovery
                        bucket: month
                        date: '2022-02-01'
                        keyword: bar
                        threshold: 42
                      - branded: branded
                        bucket: month
                        count: 9001
                        date: '2022-02-01'
                        keyword: foo
                      - branded: discovery
                        bucket: month
                        date: '2022-01-01'
                        keyword: bar
                        threshold: 42
                      - branded: branded
                        bucket: month
                        count: 9001
                        date: '2022-01-01'
                        keyword: foo
                dimensions=month,keyword,branded&branded=true:
                  value:
                    page: 1
                    count: 3
                    max_page: 1
                    keywords:
                      - branded: branded
                        bucket: month
                        count: 9001
                        date: '2022-03-01'
                        keyword: foo
                      - branded: branded
                        bucket: month
                        count: 9001
                        date: '2022-02-01'
                        keyword: foo
                      - branded: branded
                        bucket: month
                        count: 9001
                        date: '2022-01-01'
                        keyword: foo
                dimensions=month,keyword,branded&branded=false:
                  value:
                    page: 1
                    count: 3
                    max_page: 1
                    keywords:
                      - branded: discovery
                        bucket: month
                        date: '2022-03-01'
                        keyword: bar
                        threshold: 42
                      - branded: discovery
                        bucket: month
                        date: '2022-02-01'
                        keyword: bar
                        threshold: 42
                      - branded: discovery
                        bucket: month
                        date: '2022-01-01'
                        keyword: bar
                        threshold: 42
                dimensions=keyword&branded=true:
                  value:
                    page: 1
                    count: 1
                    max_page: 1
                    keywords:
                      - count: 27003
                        keyword: foo
                dimensions=branded:
                  value:
                    page: 1
                    count: 2
                    max_page: 1
                    keywords:
                      - branded: branded
                        threshold: 126
                      - branded: discovery
                        count: 27003
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
      deprecated: false
components:
  parameters:
    query_metrics_keywords:
      in: query
      name: metrics
      required: true
      description: |
        List of analytics to return.
         At least one in that list.
      schema:
        type: string
        enum:
          - count
          - threshold
        example: metrics=count,threshold
    query_dimensions_keywords:
      in: query
      name: dimensions
      required: false
      description: >
        How the returned data will be aggregated.

        At most 'business' and one time dimensions of the list.

        If no dimension is given, the request will return the sum of each metric
        for all requested days and businesses.
      schema:
        type: string
        enum:
          - business
          - keyword
          - month
          - year
          - branded
        example: dimensions=keyword,month,branded
    query_order_by_keywords:
      in: query
      name: order_by
      required: false
      description: >
        Where the object is either a dimension or a metric and is used in the
        request. At most one in the list. - before a field to order_by DESC,
        nothing for ASC

        Available dimensions: business, keyword, month, year, branded Available
        metrics: count, threshold
      schema:
        type: string
        enum:
          - <object>
          - '-<object>'
        example: order_by=-count
    pa_keywords_query_business__in:
      in: query
      name: business__in
      description: Filter by business ids
      required: false
      schema:
        type: array
        items:
          $ref: '#/components/schemas/BusinessID'
    pa_keywords_query_filter_date__gte:
      in: query
      name: filter_date__gte
      required: false
      description: |
        Filter by date.

        Return all the analytics whose `date >= given_date`.
      schema:
        type: string
        format: datetime
    pa_keywords_query_filter_date__lte:
      in: query
      name: filter_date__lte
      required: false
      description: |
        Filter by date.

        Return all the analytics whose `date <= give_date`.
      schema:
        type: string
        format: datetime
    query_branded:
      in: query
      name: branded
      required: false
      description: >
        Filter by branded status.


        - `true`: Return only branded keywords (keywords associated with your
        brand)

        - `false`: Return only discovery keywords (generic keywords not
        associated with your brand)


        If not specified, returns both branded and discovery keywords.
      schema:
        type: boolean
        example: branded=true
    pa_pagination_query_page:
      in: query
      name: page
      required: false
      description: |
        The page number you want to request.
      schema:
        type: integer
        default: 1
        minimum: 1
    pa_pagination_query_per_page:
      in: query
      name: per_page
      required: false
      description: |
        The maximum number of result items to return in a page.

        The value defaults to 500, when it is not included.
      schema:
        type: integer
        maximum: 500
  schemas:
    PresenceAnalyticsKeywordsResponse:
      type: object
      properties:
        page:
          $ref: '#/components/schemas/Page'
        count:
          $ref: '#/components/schemas/TotalItemsCount'
        max_page:
          $ref: '#/components/schemas/MaxPage'
        keywords:
          $ref: '#/components/schemas/PresenceAnalyticsKeywordsResults'
    BusinessID:
      description: Business id
      type: string
      example: 5409c35a97bbc544d8e26737
    Page:
      description: The current page number.
      type: integer
      example: 1
    TotalItemsCount:
      description: >
        Total number of results available for the filters and dimensions
        requested.
      type: integer
      example: 1
    MaxPage:
      description: Total number of pages available for this request.
      type: integer
      example: 1
    PresenceAnalyticsKeywordsResults:
      type: array
      items:
        type: object
        properties:
          keyword:
            $ref: '#/components/schemas/Keyword'
          count:
            $ref: '#/components/schemas/KeywordsCount'
          threshold:
            $ref: '#/components/schemas/Threshold'
          date:
            $ref: '#/components/schemas/KeywordsAnalyticsDate'
          bucket:
            $ref: '#/components/schemas/KeywordsAnalyticsBucket'
          business_id:
            $ref: '#/components/schemas/BusinessID'
          branded:
            $ref: '#/components/schemas/Branded'
    Keyword:
      type: string
      description: |
        The lower-cased string that the user entered.

        This is present only if the “keyword” dimension is in the request.
      example: 123
    KeywordsCount:
      type: integer
      description: >
        An aggregation of mountly keyword search count values.


        The count values indicates the number of unique users that used the
        keyword in a month.
      example: 123
    Threshold:
      type: integer
      description: >
        An aggregation of monthly threshold values.


        The threshold value indicates that the real count of unique users that
        used the keyword is below this value.
      example: 123
    KeywordsAnalyticsDate:
      type: string
      description: First day of the aggregation
      example: '2019-11-01'
    KeywordsAnalyticsBucket:
      type: string
      description: Time aggregation requested
      example: month
    Branded:
      type: string
      description: >
        Indicates whether the keyword is branded or discovery.


        - `branded`: Keywords associated with your brand (e.g., "Castorama",
        "Casto")

        - `discovery`: Generic keywords not associated with your brand (e.g.,
        "bricolage", "magasin outillage")


        This field is only present when the "branded" dimension is included in
        the request.
      enum:
        - branded
        - discovery
      example: branded
  responses:
    '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

````