Instagram Analytics API
Integrate smartmetrics into your application.
- Authentication
- Adding account to tracking
- Get analytics
- Filtration
- Pagination
- Possible errors
- Questions
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.
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]