Analytics (V1)

API reference for link analytics. The following methods are for getting statistics about your links and traffic.
Analytics endpoint URLs have changed!
An unexpected update in the structure of our backend has forced us to change the endpoint URLs for Analytics without previous notice. Please update them accordingly.
All of the following methods are based on a time frame or time period that must not exceed 60 days. If no time frame (start_date and end_date) is provided, the default will be the last 7 days from current day. All dates are in UTC and must be provided in UTC. No dates are converted on our side.
For now, no pagination is used in these methods. You can do pagination by playing with the start_date and end_date.
If you need more information to be returned in the methods, or you have any ideas for a new one, send us an email: help@returnam.com​
get
Hits by Countries
https://api.returnam.com/v1/analytics/country-hits
Returns a detailed view of hits by device type per country in the selected time frame. If no time frame is specified, the default is the last 7 days.
Request
Response
Request
Headers
x-rtrn-key
required
string
API Key
x-rtrn-secret
required
string
API Secret
Query Parameters
end_date
optional
string
End date of the time frame in UTC. End date can't be more than 45 days apart from Start Date. 
Recommended format: YYYY-MM-DD HH:MM
start_date
optional
string
Start date of the time frame in UTC. 
Recommended format: YYYY-MM-DD HH:MM
slug
optional
string
Get results only for the specified slug.
order
optional
string
The order of the results. 'asc' or 'desc'.
order_by
optional
string
Order results by 'country_code', 'country_name', 'total_hits', 'desktop_hits', 'tablet_hits', 'phone_hits', 'bot_hits', 'other_hits'.
Response
200: OK
Returns an array of objects containing the country and the device types for hits in that specific country.
[
    {
        "country_code": "US",
        "country_name": "United States",
        "desktop_hits": 35,
        "phone_hits": 113,
        "tablet_hits": 0,
        "bot_hits": 8,
        "other_hits": 0,
        "total_hits": 156
    },
    {
        "country_code": "MX",
        "country_name": "Mexico",
        "desktop_hits": 6,
        "phone_hits": 3,
        "tablet_hits": 0,
        "bot_hits": 0,
        "other_hits": 0,
        "total_hits": 9
    },
    {
        "country_code": "FR",
        "country_name": "France",
        "desktop_hits": 0,
        "phone_hits": 5,
        "tablet_hits": 0,
        "bot_hits": 0,
        "other_hits": 0,
        "total_hits": 5
    },
    {
        "country_code": "DE",
        "country_name": "Germany",
        "desktop_hits": 1,
        "phone_hits": 0,
        "tablet_hits": 0,
        "bot_hits": 0,
        "other_hits": 0,
        "total_hits": 1
    }
]
get
Hits by Slugs
https://api.returnam.com/v1/analytics/slug-hits
Returns a detailed view of hits by device type per slug in the time frame. If no time frame is specified, the default is the last 7 days
Request
Response
Request
Headers
x-rtrn-key
required
string
API Key
x-rtrn-secret
required
string
API Secret
Query Parameters
end_date
optional
string
End date of the time frame in UTC. End date can't be more than 45 days apart from Start Date. 
Recommended format: YYYY-MM-DD HH:MM
start_date
optional
string
Start date of the time frame in UTC. 
Recommended format: YYYY-MM-DD HH:MM
slug
optional
string
Get results only for the specified slug.
order
optional
string
The order of the results. 'asc' or 'desc'.
order_by
optional
string
Order results by: 'created_date', 'total_hits', 'desktop_hits', 'tablet_hits', 'phone_hits', 'bot_hits', 'other_hits'.
Response
200: OK
[
    {
        "slug": "l634juu",
        "created_date": "2019-09-10T12:26:59.000Z",
        "desktop_hits": 8,
        "phone_hits": 7,
        "tablet_hits": 0,
        "bot_hits": 0,
        "other_hits": 0,
        "total_hits": 15
    },
    {
        "slug": "og7462dg",
        "created_date": "2019-09-05T23:04:29.000Z",
        "desktop_hits": 3,
        "phone_hits": 5,
        "tablet_hits": 0,
        "bot_hits": 0,
        "other_hits": 0,
        "total_hits": 8
    },
    {
        "slug": "jh45sbt",
        "created_date": "2019-09-07T20:48:51.000Z",
        "desktop_hits": 1,
        "phone_hits": 7,
        "tablet_hits": 0,
        "bot_hits": 0,
        "other_hits": 0,
        "total_hits": 8
    }
]
get
Hits by Day
https://api.returnam.com/v1/analytics/daily-hits
Returns a detailed view of hits by device type per day in the time frame. If no time frame is specified, the default is the last 7 days.
Request
Response
Request
Headers
x-rtrn-key
required
string
API Key
x-rtrn-secret
required
string
API Secret
Query Parameters
end_date
optional
string
End date of the time frame in UTC. End date can't be more than 45 days apart from Start Date. 
Recommended format: YYYY-MM-DD HH:MM
start_date
optional
string
Start date of the time frame in UTC. 
Recommended format: YYYY-MM-DD HH:MM
slug
optional
string
Get results only for the specified slug.
order
optional
string
The order of the results. 'asc' or 'desc'.
order_by
optional
string
Order results by: 'created_date', 'total_hits', 'desktop_hits', 'tablet_hits', 'phone_hits', 'bot_hits', 'other_hits'.
Response
200: OK
Returns an array of objects with hits per day, separated by device type and total hits on that day. Day of hits is found on 'on_date'.
[
    {
        "desktop_hits": 2,
        "phone_hits": 6,
        "tablet_hits": 0,
        "bot_hits": 0,
        "other_hits": 0,
        "on_date": "2019-09-08T00:00:00.000Z",
        "total_hits": 8,
        "visited_links": 5
    },
    {
        "desktop_hits": 8,
        "phone_hits": 37,
        "tablet_hits": 0,
        "bot_hits": 0,
        "other_hits": 0,
        "on_date": "2019-09-09T00:00:00.000Z",
        "total_hits": 45,
        "visited_links": 19
    },
    {
        "desktop_hits": 12,
        "phone_hits": 33,
        "tablet_hits": 0,
        "bot_hits": 0,
        "other_hits": 0,
        "on_date": "2019-09-10T00:00:00.000Z",
        "total_hits": 45,
        "visited_links": 17
    }
]
get
Account Statistics
https://api.returnam.com/v1/analytics/account-stats
Returns some general account statistics, like total links created, hits, unique hits and countries in the specified time frame. If no time frame is specified, the default is the last 7 days.
Request
Response
Request
Headers
x-rtrn-key
required
string
API Key
x-rtrn-secret
required
string
API Secret
Query Parameters
end_date
optional
string
End date of the time frame in UTC. End date can't be more than 60 days apart from Start Date. Recommended format: YYYY-MM-DD HH:MM.
start_date
optional
string
Start date of time frame in UTC. Recommended format: YYYY-MM-DD HH:MM.
Response
200: OK
General stats retrieved.

{
    "created_links": 32, // Number of total links created
    "total_hits": 317, // Total hits for all links
    "unique_hits": 307, // Unique hits for all links
    "hit_links": 13, // Links that have hits
    "hit_countries": 26 // Countries where links were opened
}
get
Hits by Day and Country
https://api.returnam.com/v1/analytics/daily-county-hits
Same as Hits by Country, but each day has details on hits divided by countries and device types.
Request
Response
Request
Headers
x-rtrn-key
required
string
API Key
x-rtrn-secret
required
string
API Secret
Query Parameters
end_date
optional
string
End date of the time frame in UTC. End date can't be more than 45 days apart from Start Date. 
Recommended format: YYYY-MM-DD HH:MM
start_date
optional
string
Start date of the time frame in UTC. 
Recommended format: YYYY-MM-DD HH:MM
slug
optional
string
Get results only for the specified slug.
order
optional
string
The order of the results. 'asc' or 'desc'.
order_by
optional
string
Order results by 'country_code', 'country_name', 'total_hits', 'desktop_hits', 'tablet_hits', 'phone_hits', 'bot_hits', 'other_hits'.
Response
200: OK
Returns an object with dates. Each date has an array of objects containing hits by countries divided by device type.
{
    "2019-11-02": [
        {
            "country_code": "US",
            "country_name": "United States",
            "desktop_hits": 1,
            "phone_hits": 17,
            "tablet_hits": 0,
            "bot_hits": 0,
            "other_hits": 0,
            "on_date": "2019-11-02T00:00:00.000Z",
            "total_hits": 18
        }
    ],
    "2019-11-01": [
        {
            "country_code": "US",
            "country_name": "United States",
            "desktop_hits": 0,
            "phone_hits": 12,
            "tablet_hits": 0,
            "bot_hits": 0,
            "other_hits": 0,
            "on_date": "2019-11-01T00:00:00.000Z",
            "total_hits": 12
        }
    ],
    "2019-10-31": [
        {
            "country_code": "US",
            "country_name": "United States",
            "desktop_hits": 5,
            "phone_hits": 12,
            "tablet_hits": 0,
            "bot_hits": 0,
            "other_hits": 0,
            "on_date": "2019-10-31T00:00:00.000Z",
            "total_hits": 17
        },
        {
            "country_code": "FI",
            "country_name": "Finland",
            "desktop_hits": 1,
            "phone_hits": 0,
            "tablet_hits": 0,
            "bot_hits": 0,
            "other_hits": 0,
            "on_date": "2019-10-31T00:00:00.000Z",
            "total_hits": 1
        }
    ],
    "2019-10-30": [
        {
            "country_code": "MX",
            "country_name": "Mexico",
            "desktop_hits": 3,
            "phone_hits": 1,
            "tablet_hits": 0,
            "bot_hits": 0,
            "other_hits": 0,
            "on_date": "2019-10-30T00:00:00.000Z",
            "total_hits": 4
        },
        {
            "country_code": "US",
            "country_name": "United States",
            "desktop_hits": 1,
            "phone_hits": 20,
            "tablet_hits": 0,
            "bot_hits": 0,
            "other_hits": 0,
            "on_date": "2019-10-30T00:00:00.000Z",
            "total_hits": 21
        }
    ]
}
API Reference - Previous
Links (v1)
Next - API Reference
Hits (V1)
Last updated 6 months ago
Analytics (V1)

getHits by Countries

getHits by Slugs

getHits by Day

getAccount Statistics

getHits by Day and Country

get
Hits by Countries

get
Hits by Slugs

get
Hits by Day

get
Account Statistics

get
Hits by Day and Country
