.. index:: AdvertisementStatistics

.. _advertisements-statistics:

Advertisement statistics
========================


Endpoint to retrieve statistics about an advertisement.

Fields
------

Below are listed the specific statistics that are returned:

.. apifields::
    .. apifield::
        :name: numberOfViews
        :type: int
        :constraints: positive
        :required: true
        :updateable: false
        :writable: false

        The number of times the advertisement page (VIP) has been viewed.

    .. apifield::
        :name: numberOfAsqs
        :type: int
        :constraints: positive
        :required: true
        :updateable: false
        :writable: false

        The number of times a user contacted the seller of the advertisement (by sending an ASQ).

    .. apifield::
        :name: numberOfBids
        :type: int
        :constraints: positive
        :required: true
        :updateable: false
        :writable: false

        The number of bids on the advertisement.

    .. apifield::
        :name: numberOfUrlClicks
        :type: int
        :constraints: positive
        :required: true
        :updateable: false
        :writable: false

        The number of times a user clicked the URL of the advertisement.

    .. apifield::
        :name: numberOfPhoneClicks
        :type: int
        :constraints: positive
        :required: true
        :updateable: false
        :writable: false

        The number of times a user clicked the telephone number of the advertisement.

    .. apifield::
        :name: numberOfFavoriteClicks
        :type: int
        :constraints: positive
        :required: true
        :updateable: false
        :writable: false

        The number of user clicks to save this ad to their favorites. We only count the addition to the users
        favorites. In case a user removes it the number is not decremented. This means that there is a difference
        between the actual current number of users that have this ad in their favorites and the number of clicks
        tracked by this metric.

    .. apifield::
        :name: minFindabilityIndicator
        :type: int
        :constraints: positive
        :required: false
        :updateable: false
        :writable: false

        | An indication of the findability of the advertisement, returns the minimal page number for the ad to be found.
        | For example:

        - 1: Advertisement is findable from page 1 and up
        - 5: Advertisement is findable from page 5 and up
        - 10: Advertisement is finable from page 10 and up

        .. note:: this data is experimental for now, and might not be available.

    .. apifield::
        :name: maxFindabilityIndicator
        :type: int
        :constraints: positive
        :required: false
        :updateable: false
        :writable: false

        | An indication of the findability of the advertisement, returns the max page number for the ad to be found.
        | For example:

        - 5: Advertisement is findable within the first 5 pages
        - 10: Advertisement is findable within the first 10 pages
        - if this field is missing, there is no upper bound, which means it's somewhere in the results higher than or equal to the minFindabilityIndicator value

        .. note:: this data is experimental for now, and might not be available.


Reference
---------

.. endpoint:: GET /v1/advertisements/{itemId}/statistics

Retrieve statistics for a specific advertisement



Examples
--------

.. include:: examples/get-ads-statistics-example.rst