Instagram Analytics API

Integrate smartmetrics into your application.


Authentication

We use key based authentication over https for simplicity. You need register your application to obtain API key:

1. Visit developers page.

2. Add new API key.

instagram analytics api key generate

System will generate a string of 80 chars. You should pass this API key in every call as parameter key in query string.
Further in the document we will call it MY_GENERATED_KEY.



Adding account to tracking

To see analytical information related to Instagram account you need to add this account into our system.

Adding your account

Before using this endpoint you need authorize our service in Facebook using following link: https://smartmetrics.co/fb/login. This action grants us permissions to get all analytical information from Facebook API. After authorization you will be able to request a list of Instagram accounts available for tracking.


curl -i -H "Accept: application/json" https://smartmetrics.co/api/available-instagram-accounts/?key=MY_GENERATED_KEY


HTTP 200 OK
Allow: GET
Content-Type: application/json
Vary: Accept

[
    {
        "data": [
            {
                "username": "<< Instagram Account name >>",
                "already_tracked": false,
                "fb_owner": "<< ID of Facebook user that has permission to track account >>",
                "profile_picture_url": "<< Link to Instagram user picture >>",
                "page_id": "<< ID of Facebook page connected to Instagram account >>",
                "id": "<< ID of Instagram account >>"
            },
            ...
        ],
        "name": "Your Facebook Name"
    }
]

To start tracking you need call following endpoint with two params: id and fb_owner


curl -X POST \
  https://smartmetrics.co/api/add-instagram-account/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'key=MY_GENERATED_KEY&id=ID&fb_owner=FB_OWNER'


Adding other account / competitor

This endpoint will start account tracking as Competitor by username.


curl -X POST \
  https://smartmetrics.co/api/add-instagram-competitor/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'key=MY_GENERATED_KEY&username=USERNAME'


HTTP 200 OK
Allow: POST
Content-Type: application/json
Vary: Accept

{"details":"We are processing account. We will send you email as soon as everything is ready."}



Get analytics

All endpoints are only accessible via https and are located at smartmetrics.co/api/.

List of tracked users

This endpoint returns data of all your tracked accounts. Every tracked account has an Instagram user ID, you need to know this ID to make user related API calls.


curl -i -H "Accept: application/json" https://smartmetrics.co/api/tracked-users/?key=MY_GENERATED_KEY


HTTP 200 OK
Allow: GET
Content-Type: application/json
Vary: Accept

{
    "count": 36,
    "next": "https://smartmetrics.co/api/tracked-users/?key=MY_GENERATED_KEY&page=2",
    "previous": null,
    "results": [
        {
            "user_id": 17841405945557682,
            "username": "apple",
            "owned": false
        },
        {
            "user_id": 17841401117380673,
            "username": "bmw",
            "owned": false
        },
        ...
    ]
}


Audience metrics

Audience metrics endpoint represents data that are presented on audience page.
Parameter user_id is mandatory.
Data set in response depends on type of tracked account: owned or competitor.


curl -i -H "Accept: application/json" https://smartmetrics.co/api/audience/?key=MY_GENERATED_KEY&user_id=17841405945557682"


HTTP 200 OK
Allow: GET
Content-Type: application/json
Vary: Accept

{
    "count": 399,
    "next": "https://smartmetrics.co/api/audience/?key=MY_GENERATED_KEY&page=2&user_id=17841405945557682",
    "previous": null,
    "results": [
        {
            "timestamp": "2018-09-12T11:59:25.425796Z",
            "followers": 7598023,
            "followers_change": 19543,
            "follows": null,
            "followers_hourly_change": [
                741,
                454,
                583,
                643,
                552,
                -9,
                1101,
                580,
                -18,
                681,
                705,
                775,
                ...
            ],
            "influence": null,
            "media_count": 255,
            "user_id": 17841405945557682
        },
        ...
    ]
}


Posts metrics

Posts metrics endpoint represents data that are presented on posts page.
Parameter user_id is mandatory.
Data set in response depends on type of tracked account: owned or competitor.


curl -i -H "Accept: application/json" https://smartmetrics.co/api/posts-metrics/?key=MY_GENERATED_KEY&user_id=17841405945557682"


HTTP 200 OK
Allow: GET
Content-Type: application/json
Vary: Accept

{
    "count": 401,
    "next": "https://smartmetrics.co/api/posts-metrics/?key=MY_GENERATED_KEY&page=2&user_id=17841405945557682",
    "previous": null,
    "results": [
        {
            "timestamp": "2018-09-12T11:59:25.425796Z",
            "media_total": 257,
            "media_photo": 129,
            "media_video": 65,
            "media_albums": 63,
            "today_photo": 0,
            "today_video": 0,
            "today_albums": 0,
            "new_interactions_total": 110486,
            "new_interactions_photo": 107818,
            "new_interactions_photo_comments": 276,
            "new_interactions_photo_likes": 107542,
            "new_interactions_video": 2491,
            "new_interactions_video_comments": null,
            "new_interactions_video_likes": 2512,
            "new_interactions_album": null,
            "new_interactions_album_comments": null,
            "new_interactions_album_likes": 178,
            "post_engagement_ratio_total": 1.5,
            "post_engagement_ratio_photo": 2.0,
            "post_engagement_ratio_video": 0.84,
            "post_engagement_ratio_album": 1.15,
            "profile_engagement_ratio": 1.45,
            "engagement_hourly_change": [
                7960,
                5436,
                7600,
                7661,
                7295,
                7228,
                6797,
                5781,
                5079,
                ...
            ],
            "user_id": 17841405945557682
        },
        ...
    ]
}


Stories metrics

Stories metrics endpoint represents data that are presented on stories page.
Parameter user_id is mandatory.
This endpoint works only for owned accounts.


curl -i -H "Accept: application/json" https://smartmetrics.co/api/stories-metrics/?key=MY_GENERATED_KEY&user_id=17841405945557682"

Data format in response is the same as for post endpoint. Some stories specific fields will be added to each record.


{
    "new_interactions_photo_replies": 0,
    "new_interactions_video_replies": 0,
    "new_taps_forward": 0,
    "new_taps_forward_photo": 0,
    "new_taps_forward_video": 0,
    "new_taps_back": 0,
    "new_taps_back_photo": 0,
    "new_taps_back_video": 0,
    "new_replies": 0,
    "new_replies_photo": 0,
    "new_replies_video": 0,
    "new_exits": 0,
    "new_exits_photo": 0,
    "new_exits_video": 0,
    "bounce_rate": 0.0,
    "bounce_rate_photo": 0.0,
    "bounce_rate_video": 0.0,
}


Posts

Posts endpoint represents raw data for all your posts.
Parameter user_id is mandatory.
Data set in response depends on type of tracked account: owned or competitor.


curl -i -H "Accept: application/json" https://smartmetrics.co/api/posts/?key=MY_GENERATED_KEY&user_id=17841405945557682"


HTTP 200 OK
Allow: GET
Content-Type: application/json
Vary: Accept

{
    "count": 257,
    "next": "https://smartmetrics.co/api/posts/?key=MY_GENERATED_KEY&page=2&user_id=17841405945557682",
    "previous": null,
    "results": [
        {
            "timestamp": "2018-09-10T17:46:58Z",
            "caption": "\"Wherever adventure can be found.\" #ShotoniPhone by Alex M. alex.motyka + Charlotte M. charlottemasonn",
            "media_type": "image",
            "shortcode": "BnjfPCsjunD",
            "comments": 679,
            "likes": 204428,
            "engagement": 205107,
            "interactions_48": [
                0,
                35545,
                18814,
                12332,
                8670,
                6883,
                7137,
                4837,
                6752,
                6779,
                6537,
                ...
            ],
            "er": 0.0269947853540322,
            "thumbnail_url": null,
            "hashtags": [
                "ShotoniPhone"
            ],
            "user_id": 17841405945557682
        },
        ...
    ]
}


Stories

Stories endpoint represents raw data for your stories posted since your account was connected to smartmetrics.
Parameter user_id is mandatory.
This endpoint works only for owned accounts.


curl -i -H "Accept: application/json" https://smartmetrics.co/api/stories/?key=MY_GENERATED_KEY&user_id=17841405945557682"

Data format in response is the same as for post endpoint. Some stories specific fields will be added to each record.



Filtration

Filtration by dates is available for all endpoints which contain timestamp in results.
To filter results by date yo can add date_from and/or date_till parameters.
Date format: YYYY-MM-DD or YYYYMMDD.


https://smartmetrics.co/api/posts/?user_id=17841405945557682&key=MY_GENERATED_KEY&date_from=2018-08-01&date_till=2018-08-31

This request returns all post made in August 2018.



Pagination

All responses are limited by 30 results per response. The rest of data are paginated by pages.
API shows count of results and fields 'next' and 'previous'.


curl -i -H "Accept: application/json" https://smartmetrics.co/api/posts/?key=MY_GENERATED_KEY&user_id=17841405945557682"


HTTP 200 OK
Allow: GET
Content-Type: application/json
Vary: Accept

{
    "count": 257,
    "next": "https://smartmetrics.co/api/posts/?key=MY_GENERATED_KEY&page=2&user_id=17841405945557682",
    "previous": null,
    "results": [
    ...
    ]
}

These fields contain links to next or previous page, you can walk by pages simply by add parameter page to your request.



Possible errors

1. No API key provided.
Just add your generated key to request.


curl -i -H "Accept: application/json" https://smartmetrics.co/api/


HTTP/1.0 403 Forbidden
Content-Type: application/json
Allow: GET, HEAD, OPTIONS

{"detail":"Authentication credentials were not provided."}


2. Wrong API key.
Check you provide correct API key. Please note your IP address will be blocked for 15 minutes after 5 retries using wrong key.


curl -i -H "Accept: application/json" https://smartmetrics.co/api/?key=12345


HTTP/1.0 403 Forbidden
Content-Type: application/json
Allow: GET, HEAD, OPTIONS

{"detail":"Wrong authentication key. Failures before block: 5"}


3. Billing or subscription issues.
Check whether your subscription is active.


curl -i -H "Accept: application/json" https://smartmetrics.co/api/?key=12345678


HTTP/1.0 403 Forbidden
Content-Type: application/json
Allow: GET, HEAD, OPTIONS

{"detail":"Billing issue. Please check billing page or contact [email protected]"}


4. Account is not owned.
You try to get information for account you track as competitor.


curl -i -H "Accept: application/json" https://smartmetrics.co/api/stories-metrics/?key=12345678&user_id=007


HTTP/1.0 403 Forbidden
Content-Type: application/json
Allow: GET, HEAD, OPTIONS

{"detail": "This method is available only for accounts owned by you."}


5. No paid subscription.
API available only for users with paid subscriptions and not available during trial period.


curl -i -H "Accept: application/json" https://smartmetrics.co/api/stories-metrics/?key=12345678&user_id=007


HTTP/1.0 403 Forbidden
Content-Type: application/json
Allow: GET, HEAD, OPTIONS

{"detail": "API unavailable during trial period."}



Questions and comments

We are able to add more features and endpoints by your request.
To ask questions about our API you may contact us at [email protected]