API Statistics

The Vantevo API offers a way to retrieve your code level statistics.

The API accepts GET requests along with query parameters and returns standard HTTP responses along with a JSON type body. All API requests must be made via HTTPS.

Each request must be authenticated with an API key using the Bearer Token method. You can get an API key for your account by going to your account settings page.

Parameters

period

period ^Required

day - today
yesterday - yesterday
1m - this month
1y - this year
7d - last 7 days
30d - last 30 days
6m - last 6 months
12m - last 12 months
custom - you can insert a custom date header

When using a custom range, you need to add two more ISO-8601 formatted date parameters; start and end. The statistics will be returned for the entire date range between start and end dates.

start - "yyyy-mm-dd"
end - "yyyy-mm-dd"

domain

domain ^Required

Enter the domain name saved on Vantevo Analytics.

source

source ^Required

Source	Description
`totals`	Get the number of unique visitors, bounce rate, sessions, average duration and page numbers displayed of the current and previous period, it helps you make the comparison between the 2 periods.
`pages`	List with all visited pages
`entry-pages`	List with all entry pages
`exit-pages`	List with all exit pages
`referrals`	LList with all the refferals
`utm-source`	UTM source
`utm-medium`	UTM medium
`utm-campaign`	UTM campaign
`utm-content`	UTM content
`utm-term`	UTM term
`devices`	List with all types of devices
`browsers`	List with all types of browsers
`os`	List with all operating systems
`screen`	List with all screen sizes
`countries`	List with all the countries of your visitors
`regions`	List with all the regions of your visitors
`cities`	List with all the cities of your visitors
`languages`	List with all the languages of your visitors
`goals`	List with all the goals
`events`	List with all the events

limit

limit ^Optional

Default: 30

It allows you to manage the pagination system. The maximum number you can ask for is 50 records.

offset

offset ^Optional

Default: 0

It allows you to manage the pagination system.

filters

Optional

The following list contains all possible filter options.

Filtro	Descrizione
`page`	It allows you to filter results based on a specific page, the value of the field must be a pathname, e.g.: `/contacts`
`entry_page`	It allows you to filter results based on a specific entry page, the value of the field must be a pathname, e.g.: `/`
`exit_page`	Allows you to filter results based on a specific exit page, the value of the field must be a pathname, e.g.: `/`
`device`	It allows you filter results by device, e.g.: `Desktop`
`os`	It allows you to filter results by operating system, e.g.: `Windows`
`os_version`	It allows you to filter the results according to the operating system version, e.g.: `10`. It works together with the `os` filter.
`browser`	It allows you to filter results by browser name, e.g.: `Chrome`
`browser_version`	It allows you to filter results by browser version, e.g.: `100.0.4896.75`. It works together with the `browser` filter.
`screen_class`	It allows you to filter results by screen size, e.g.: `XL`
`country`	It allows you to filter results by country, e.g.: `IT`
`region`	It allows you to filter results by region, e.g.: `Lazio`
`city`	It allows you to filter results by city, e.g.: `Rome`
`language`	It allows you to filter results by language, e.g.: `IT`
`referrer_name`	It allows you to filter results by referrer, e.g.:`Bing`
`referrer`	It allows you to filter results by referrer, e.g.: `https://bing.com`
`utm_source`	t allows you to filter results by parameter UTM Source
`utm_medium`	t allows you to filter results by parameter UTM Medium
`utm_campaign`	t allows you to filter results by parameter UTM Campaign
`utm_content`	t allows you to filter results by parameter UTM Content
`utm_term`	t allows you to filter results by parameter UTM Term
`event`	It allows you to filter results based on a specific event, such as: `File Download`, this filter is used in event requests.
`event_key`	It allows you to filter results by `event_key` value, this filter is used in event requests.
`event_value`	It allows you to filter results by `event_value`, this filter is used in event requests.
`goals`	It allows you to filter results for a specific goal.

Error handling

401 - when one of the mandatory parameters is missing or one of the parameters is invalid
200 - message Wrong period filter. - the value of the period parameter is wrong
200 - message Wrong start date time. - the value of the start parameter is wrong
200 - message Wrong end date time. - the value of the end parameter is wrong

Statistics

The following endpoints can be used to read statistics from Vantevo.

GET /v1/stats

source totals examples

With this request you get: number of unique visitors, number of visited pages, bounce frequency, sessions and the average duration of the current and previous period, it helps you to make the comparison between the 2 periods

totals request
curl --location --request GET 'https://api.vantevo.io/v1/stats?period=1m&domain=example.com&source=totals' \
--header 'Authorization: Bearer {token} \

respond
{
  "current": {
    "visitors": 206,
    "bounce_rate": 57.82,
    "duration": 42,
    "sessions": 211,
    "page_views": 410
  },
  "last": {
    "visitors": 199,
    "bounce_rate": 50.95,
    "duration": 83,
    "sessions": 210,
    "page_views": 504
  }
}

Esempio source pages

Return to the all visited pages list

Richiesta pages
curl --location --request GET 'https://api.vantevo.io/v1/stats?period=1m&domain=example.com&source=pages' \
--header 'Authorization: Bearer {token} \

respond
{
    "data": [
       {
            "visitors": 95,
            "path": "/",
            "title": "Example Title",
            "domain": "https://www.example.com",
            "visits": 121,
            "duration": 14,
            "bounce": 38,
            "count": 96
        },
        ...
    ]
}

Source referrals examples

Return to the list of all referrals

referrals request
curl --location --request GET 'https://api.vantevo.io/v1/stats?period=1m&domain=example.com&source=referrals' \
--header 'Authorization: Bearer {token} \

respond
{
    "data": [
       {
            "name": "Google",
            "referrer": "https://www.google.com",
            "visitors": 109
        },
        ...
    ]
}

Source OS examples

Return to the list of all your visitors' operating systems

os request
curl --location --request GET 'https://api.vantevo.io/v1/stats?period=1m&domain=example.com&source=os' \
--header 'Authorization: Bearer {token} \

respond
{
    "data": [
       {
            "name": "Windows",
            "visitors": 715
        },
        ...
    ]
}

Source pages example with browser filter

Return to the all-pages list filtered by browser

request
curl --location --request GET 'https://api.vantevo.io/v1/stats?period=1m&domain=example.com&source=pages&browser=Chrome' \
--header 'Authorization: Bearer {token} \

respond
{
    "data": [
         {
            "visitors": 95,
            "path": "/",
            "title": "Example Title",
            "domain": "https://www.example.com",
            "visits": 99,
            "duration": 12,
            "bounce": 24,
            "count": 12
        },
        ...
    ]
}

Events

The following endpoints can be used to read event statistics from Vantevo.

GET /v1/events

Source totals example

With this request you get: number of unique visitors, number of unique events, total events and total visitors of the current and previous period, it helps you to make the comparison between the 2 periods.

request
curl --location --request GET 'https://api.vantevo.io/v1/events?period=1m&domain=example.com&source=totals' \
--header 'Authorization: Bearer {token} \

respond
{
  "current": {
    "visitors": 326,
    "events": 71,
    "unique_events": 3,
    "uniq_visitors": 57
  },
  "last": {
    "visitors": 175,
    "events": 41,
    "unique_events": 1,
    "uniq_visitors": 22
  }
}

Source events example

Return to the list of all your visitors events

request
curl --location --request GET 'https://api.vantevo.io/v1/events?period=1m&domain=example.com&source=events' \
--header 'Authorization: Bearer {token} \

respond
{
    "data": [
        {
            "name": "Search",
            "events": 122,
            "visitors": 52,
            "duration": 0
        },
        {
            "name": "Outbound Link",
            "events": 44,
            "visitors": 23,
            "duration": 0
        }
        ...
    ]
}

Source events example with page filter

Return the list of all your visitors' events filtered by a specific page

request
curl --location --request GET 'https://api.vantevo.io/v1/events?period=1m&domain=example.com&source=events&page=%2Fexample' \
--header 'Authorization: Bearer {token} \

respond
{
    "data": [
         {
            "name": "Video Example",
            "events": 60,
            "visitors": 47,
            "duration": 29
        }
        ...
    ]
}

Parameters​

period​

domain​

source​

limit​

offset​

filters​

Error handling​

Statistics​

GET /v1/stats​

source totals examples​

Esempio source pages​

Source referrals examples​

Source OS examples​

Source pages example with browser filter​

Events​

GET /v1/events​

Source totals example​

Source events example​

Source events example with page filter​