dd.apib

FORMAT: 1A
HOST: https://api.influencerdb.com

# InfluencerDB API

## version 1.0.0

Documentation of InfluencerDB API version 1.0.0

## Authentication

For clients to authenticate, the token key should be included in the Authorization HTTP header.
The key should be prefixed by the string literal "Token", with whitespace separating the two strings.
For example:

```
    Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b
```

The following tokens are used through this documentation:

* `9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b` - Normal user, has sufficient credits
* `90f31a4946ba3dd8ce444c24f63720dab7324299` - Normal user, has no credits
* `a3a9cb7760b56e79a378890adf5808666c369ffd` - Token does not belong to a user


## Credit point system

Each API call will cost the customer a specific amount of credit points. Every call costs, even for the same data.

The customer has a set amount of monthly API credit points that reset on a subscription renewal/downgrade, and
they should be able to buy more points with the help of a sales team member (no self service in the short term).

Amount of credits available to the user can be obtained with `/balance` endpoint.

Amount of credits required to execute call can be obtained with `OPTIONS` request to the desired endpoint.

## Country format

Coutry codes are provided in ISO 3166-1 alpha-2 format (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

## Date format

Dates are provided in ISO 8601 format (https://en.wikipedia.org/wiki/ISO_8601)

Example:

```
    2018-07-12
```

## Errors

API responds with standard HTTP status codes:

* **401 Not authorized** - The user cannot be authorized. Authentication token is missing or incorrect.
* **403 Forbidden** - The user does not have access to the resource. Credit balance is insufficient to complete the call
* **404 Not found** - The requested object is not found
* **405 Method not allowed** - This HTTP request method is not allowed for this endpoint
* **429 Too Many Requests** - The user has insufficient credits to issue this call

# Data Structures

## Api Metadata (object)

- version: 1.0.0 (string, required) - Version of the API impementation

## Category (object)

+ name: `travel` (string, required)

## Channel (object)

+ id: `d15ea3bc-c59a-49da-a6d2-f5e66fd44b71` (string, required) - unique ID of the channel
+ username: `dior` (string, required) - channel username
+ media: `instagram` (string, required) - channel media
+ category (object)
  + primary (array[Category], required)
  + secondary (array[Category], required)
+ country: `US` (string, required) - channel original country
+ stats (object, required, fixed-type)
  + followers: `1234` (number, required)
  + follows: `5678` (number, required)
  + post_count: `345` (number, required)

## ChannelSearchResult (object, fixed-type)

+ count: `1` (number, required) - Number of items in the result
+ next: `null` (string, nullable, required)
+ previous: `null` (string, nullable, required)
+ results (array[Channel], fixed-type)

## ChannelAudienceAnalytics (object, fixed-type)

+ genders (object, required, fixed-type)
    + male: `43.7` (number, required)
    + femalte: `56.3` (number, required)
+ countries (object, required)
    + US: `56.1` (number)
    + ID: `1.8` (number)
+ ages (object, required, fixed-type)
    + total: 606 (number, required)
    + counts (array, required)
        + (array)
            + `25-34` (string, required)
            + `123` (number, required)

## ChannelAudienceQuality (object, fixed-type)

+ quality_grade: `55` (number, required) - Quality grade value (from 0 to 100)
+ quality_distribution (object, required, fixed-type)
  + quality_distribution_1: `0.47638009` (number, required)
  + quality_distribution_2: `0.15819005` (number, required)
  + quality_distribution_3: `0.10895928` (number, required)
  + quality_distribution_4: `0.15565611` (number, required)
  + quality_distribution_5: `0.10081448` (number, required)

## ChannelMentionEntry (object, fixed-type)

- username: `someuser` (string, required) - Username who mentions this channel
- profile_picture: `https://scontent.cdninstagram.com/something.jpg` (string, required) - User picture

## ChannelMentions (object, fixed-type)

+ count: `1` (number, required)
+ next: `null` (string, nullable, optional)
+ previous: `null` (string, nullable, optional)
+ results (array[ChannelMentionEntry], required)

## ChannelFollowerChangeEntry (object, fixed-type)

- date: `2012-04-23` (string, required)
- followers: `5982` (number, required)
- change: `10` (number, required) - Change in %
- follows: `132` (number, required)

## ChannelFollowerChanges (object, fixed-type)

+ count: `1` (number, required)
+ next: `null` (string, nullable, optional)
+ previous: `null` (string, nullable, optional)
+ results (array[ChannelFollowerChangeEntry], required)

## ChannelEngagedInfluencerEntry (object, fixed-type)

- id: `d15ea3bc-c59a-49da-a6d2-f5e66fd44b71` (string, required)
- profile_picture: `https://scontent.cdninstagram.com/something.jpg` (string, required) - User picture

## ChannelEngagedInfluencers (object, fixed-type)

+ count: `1` (number, required)
+ next: `null` (string, nullable, optional)
+ previous: `null` (string, nullable, optional)
+ results (array[ChannelEngagedInfluencerEntry], required)

## Post (object, fixed-type)

- post_id: `d15ea3bc-c59a-49da-a6d2-f5e66fd44b71` (string, required)
- created_time: `2018-08-13T16:53:53` (string, required)
- caption  (string, required)
- tags (array[string], required)
- link: `https://www.instagram.com/p/BmbS5r4Aant` (string, required)

## ChannelContent (object, fixed-type)

+ count: `1` (number, required) - Total number of items in the response
+ next: `null` (string, nullable, required)
+ previous: `null` (string, nullable, required)
+ results (array[Post], required, fixed-type)

## Credits (object, fixed-type)

- credits: `10` (number, required) - Amount of credits available to the user

## EmptyPaginatedResult (object, fixed-type)

+ count: 0 (number, required) - Number of items in the result
+ next: null (string, nullable, required)
+ previous: null (string, nullable, required)
+ results (array[], fixed-type)

## ErrorBadRequest (object, fixed-type)

- detail: Invalid value (string, required)

## ErrorNotAuthorized (object, fixed-type)

- detail: Not authorized (string, required)

## ErrorForbidden (object, fixed-type)

- detail: Forbidden (string, required)

## ErrorNotFound (object, fixed-type)

- detail: Not found (string, required)

## ErrorInternalError (object, fixed-type)

- detail: Internal error (string, required)

## ErrorThrottledError (object, fixed-type)

- detail: Not enough credits (string, required)

# Group Meta

## Root [GET /v1/]

Root endpoint provides general meta information about version 1 of the API.

+ Request
  + Headers

            Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b


+ Response 200 (application/json)

  + Attributes (Api Metadata)

# Group Channels

# Search [/v1/channels/search{?username,media,page}]

## Retrieve [GET]

Search for channel by username and media.

+ Parameters
  + username: `dior` (string, required) - Username of user to find
  + media: `instagram` (string, optional) - Channel media. Currently the only supported value is `instagram`
  + page: `1` (int, optional) - Page, starting from 1

+ Request
  + Headers

            Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

+ Response 200 (application/json)
  + Attributes (ChannelSearchResult)

+ Request
  + Headers

            Authorization: Token a3a9cb7760b56e79a378890adf5808666c369ffd

+ Response 401 (application/json)
  + Attributes (ErrorNotAuthorized)

## Options [OPTIONS]

+ Parameters
  + username: dior (string, optional) - Username of user to find
  + media: instagram (string, optional) - Channel media. Currently the only supported value is `instagram`
  + page: 1 (int, optional) - Page, starting from 1

+ Request
  + Headers

            Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

+ Response 200 (application/json)

         {"credits": 5}

+ Request
  + Headers

            Authorization: Token a3a9cb7760b56e79a378890adf5808666c369ffd

+ Response 401 (application/json)
  + Attributes (ErrorNotAuthorized)

# Channel details [/v1/channels/{id}]

## Retrieve [GET]

Retrieve channel information

+ Parameters
  + id: `d15ea3bc-c59a-49da-a6d2-f5e66fd44b71` (string, required) - Channel ID

+ Request
  + Headers

            Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

+ Response 200 (application/json)
  + Attributes (Channel)

+ Request
  + Headers

            Authorization: Token a3a9cb7760b56e79a378890adf5808666c369ffd

+ Response 401 (application/json)
  + Attributes (ErrorNotAuthorized)

+ Response 404 (application/json)
  + Attributes (ErrorNotFound)


## Options [OPTIONS]

+ Parameters
  + id: `d15ea3bc-c59a-49da-a6d2-f5e66fd44b71` (string, required) - Channel ID

+ Request
  + Headers

            Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

+ Response 200 (application/json)

        {"credits": 5}

+ Request
  + Headers

            Authorization: Token a3a9cb7760b56e79a378890adf5808666c369ffd

+ Response 401 (application/json)
  + Attributes (ErrorNotAuthorized)

# Group Channel Analytics

# Audience [/v1/channels/{id}/analytics/audience]

## Retrieve [GET]

+ Parameters
  + id: `d15ea3bc-c59a-49da-a6d2-f5e66fd44b71` (string, required) - Channel ID

+ Request
  + Headers

            Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

+ Response 200
  + Attributes (ChannelAudienceAnalytics)

+ Request
  + Headers

            Authorization: Token a3a9cb7760b56e79a378890adf5808666c369ffd

+ Response 401 (application/json)
  + Attributes (ErrorNotAuthorized)

+ Response 403 (application/json)
  + Attributes (ErrorForbidden)

+ Response 404 (application/json)
  + Attributes (ErrorNotFound)

+ Request
  + Headers

            Authorization: Token 90f31a4946ba3dd8ce444c24f63720dab7324299

+ Response 429 (application/json)
  + Attributes (ErrorThrottledError)

## Options [OPTIONS]

+ Parameters
  + id: `d15ea3bc-c59a-49da-a6d2-f5e66fd44b71` (string, required) - Channel ID

+ Request
  + Headers

            Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

+ Response 200 (application/json)

        {"credits": 5}

+ Response 401 (application/json)
  + Attributes (ErrorNotAuthorized)

# Quality [/v1/channels/{id}/analytics/quality]

## Retrieve [GET]

+ Parameters
  + id: `d15ea3bc-c59a-49da-a6d2-f5e66fd44b71` (string, required) - Channel ID

+ Request
  + Headers

            Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

+ Response 200 (application/json)
  + Attributes (ChannelAudienceQuality, fixed-type)

+ Request
  + Headers

            Authorization: Token a3a9cb7760b56e79a378890adf5808666c369ffd

+ Response 401 (application/json)
  + Attributes (ErrorNotAuthorized)

+ Response 403 (application/json)
  + Attributes (ErrorForbidden)

+ Response 404 (application/json)
  + Attributes (ErrorNotFound)

+ Request
  + Headers

            Authorization: Token 90f31a4946ba3dd8ce444c24f63720dab7324299

+ Response 429 (application/json)
  + Attributes (ErrorThrottledError)

## Options [OPTIONS]

+ Parameters
  + id: `d15ea3bc-c59a-49da-a6d2-f5e66fd44b71` (string, required) - Channel ID

+ Request
  + Headers

            Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

+ Response 200 (application/json)

        {"credits": 5}

+ Response 401 (application/json)
  + Attributes (ErrorNotAuthorized)

# Incoming mentions [/v1/channels/{id}/analytics/mentions/incoming]

## Retrieve [GET]

+ Parameters
  + id: `d15ea3bc-c59a-49da-a6d2-f5e66fd44b71` (string, required) - Channel ID

+ Request
  + Headers

            Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

+ Response 200 (application/json)
  + Attributes (ChannelMentions, fixed-type)

+ Request
  + Headers

            Authorization: Token a3a9cb7760b56e79a378890adf5808666c369ffd

+ Response 401 (application/json)
  + Attributes (ErrorNotAuthorized)

+ Response 403 (application/json)
  + Attributes (ErrorForbidden)

+ Response 404 (application/json)
  + Attributes (ErrorNotFound)

+ Request
  + Headers

            Authorization: Token 90f31a4946ba3dd8ce444c24f63720dab7324299

+ Response 429 (application/json)
  + Attributes (ErrorThrottledError)

## Options [OPTIONS]

+ Parameters
  + id: `d15ea3bc-c59a-49da-a6d2-f5e66fd44b71` (string, required) - Channel ID

+ Request
  + Headers

            Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

+ Response 200 (application/json)

        {"credits": 5}

+ Request
  + Headers

            Authorization: Token a3a9cb7760b56e79a378890adf5808666c369ffd

+ Response 401 (application/json)
  + Attributes (ErrorNotAuthorized)

# Outgoing mentions [/v1/channels/{id}/analytics/mentions/outgoing]

## Retrieve [GET]

+ Parameters
  + id: `d15ea3bc-c59a-49da-a6d2-f5e66fd44b71` (string, required) - Channel ID

+ Request
  + Headers

            Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

+ Response 200 (application/json)
  + Attributes (ChannelMentions, fixed-type)

+ Request
  + Headers

            Authorization: Token a3a9cb7760b56e79a378890adf5808666c369ffd

+ Response 401 (application/json)
  + Attributes (ErrorNotAuthorized)

+ Response 403 (application/json)
  + Attributes (ErrorForbidden)

+ Response 404 (application/json)
  + Attributes (ErrorNotFound)

+ Request
  + Headers

            Authorization: Token 90f31a4946ba3dd8ce444c24f63720dab7324299

+ Response 429 (application/json)
  + Attributes (ErrorThrottledError)

## Options [OPTIONS]

+ Parameters
  + id: `d15ea3bc-c59a-49da-a6d2-f5e66fd44b71` (string, required) - Channel ID

+ Request
  + Headers

            Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

+ Response 200 (application/json)

        {"credits": 5}

+ Request
  + Headers

            Authorization: Token a3a9cb7760b56e79a378890adf5808666c369ffd

+ Response 401 (application/json)
  + Attributes (ErrorNotAuthorized)

# Follower changes [/v1/channels/{id}/analytics/follower-changes{?period}]

## Retrieve [GET]

+ Parameters
  + id: `d15ea3bc-c59a-49da-a6d2-f5e66fd44b71` (string, required) - Channel ID
  + period: 90 (int, optional) - Period in days. Allowed values: 90, 180, 360

+ Request
  + Headers

            Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

+ Response 200 (application/json)
  + Attributes (ChannelFollowerChanges, fixed-type)

+ Request
  + Headers

            Authorization: Token a3a9cb7760b56e79a378890adf5808666c369ffd

+ Response 401 (application/json)
  + Attributes (ErrorNotAuthorized)

+ Response 403 (application/json)
  + Attributes (ErrorForbidden)

+ Response 404 (application/json)
  + Attributes (ErrorNotFound)

+ Request
  + Headers

            Authorization: Token 90f31a4946ba3dd8ce444c24f63720dab7324299

+ Response 429 (application/json)
  + Attributes (ErrorThrottledError)

## Options [OPTIONS]

+ Parameters
  + id: `d15ea3bc-c59a-49da-a6d2-f5e66fd44b71` (string, required) - Channel ID
  + period: 90 (int, optional) - Period in days. Allowed values: 90, 180, 360

+ Request
  + Headers

            Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

+ Response 200 (application/json)

        {"credits": 5}

+ Response 401 (application/json)
  + Attributes (ErrorNotAuthorized)

# Engaged [/v1/channels/{id}/analytics/engaged]

## Retrieve [GET]

Top Engaged influencers (top 100 of the influencer's followers sorted by the followers' count)

+ Parameters
  + id: `d15ea3bc-c59a-49da-a6d2-f5e66fd44b71` (string, required) - Channel ID

+ Request
  + Headers

            Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

+ Response 200 (application/json)
  + Attributes (ChannelEngagedInfluencers, fixed-type)

+ Request
  + Headers

            Authorization: Token a3a9cb7760b56e79a378890adf5808666c369ffd

+ Response 401 (application/json)
  + Attributes (ErrorNotAuthorized)

+ Response 403 (application/json)
  + Attributes (ErrorForbidden)

+ Response 404 (application/json)
  + Attributes (ErrorNotFound)

+ Request
  + Headers

            Authorization: Token 90f31a4946ba3dd8ce444c24f63720dab7324299

+ Response 429 (application/json)
  + Attributes (ErrorThrottledError)

## Options [OPTIONS]

+ Parameters
  + id: `d15ea3bc-c59a-49da-a6d2-f5e66fd44b71` (string, required) - Channel ID

+ Request
  + Headers

            Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

+ Response 200 (application/json)

        {"credits": 5}

+ Response 401 (application/json)
  + Attributes (ErrorNotAuthorized)

# Group Channel Content

# Content [/v1/channels/{id}/content{?page}]

## Retrieve [GET]

List of content entries

+ Parameters
  + id: `d15ea3bc-c59a-49da-a6d2-f5e66fd44b71` (string, required) - Channel ID
  + page: 1 (int, optional) - Page, starting from 1

+ Request
  + Headers

            Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

+ Response 200 (application/json)
  + Attributes (ChannelContent, fixed-type)

+ Request
  + Headers

            Authorization: Token a3a9cb7760b56e79a378890adf5808666c369ffd

+ Response 401 (application/json)
  + Attributes (ErrorNotAuthorized)

+ Response 403 (application/json)
  + Attributes (ErrorForbidden)

+ Response 404 (application/json)
  + Attributes (ErrorNotFound)

+ Request
  + Headers

            Authorization: Token 90f31a4946ba3dd8ce444c24f63720dab7324299

+ Response 429 (application/json)
  + Attributes (ErrorThrottledError)

## Options [OPTIONS]

+ Parameters
  + id: `d15ea3bc-c59a-49da-a6d2-f5e66fd44b71` (string, required) - Channel ID
  + page: 1 (int, optional) - Page, starting from 1

+ Request
  + Headers

            Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

+ Response 200 (application/json)

        {"credits": 5}

+ Request
  + Headers

            Authorization: Token a3a9cb7760b56e79a378890adf5808666c369ffd

+ Response 401 (application/json)
  + Attributes (ErrorNotAuthorized)

# Group Account

Endpoints related to client's account properties

## Credits balance [GET /v1/account/balance]

Get credit balance for the user

+ Request
  + Headers

            Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

+ Response 200 (application/json)
  + Attributes (Credits)

+ Request
  + Headers

            Authorization: Token a3a9cb7760b56e79a378890adf5808666c369ffd

+ Response 401 (application/json)
  + Attributes (ErrorNotAuthorized)