Traackr API v1.0

• Influencers

  • List Methods
  • Expand Methods

  • POSTInfluencer Add/influencers/add
    Add an Influencer to the system via their name and primary URL.
    
    

    Parameter	Value	Type	Description
    name		string	Influencer name
    url		string	Influencer's primary URL (e.g. blog or website)
    customer_key		string	The customer key associated with your account. Contact api-support@traackr.com to have one issued to you
    tags		string	Tag strings(s) to add to the profile, comma-separated. Tagged profiles can then be searched through these tags

    Expect Responses

    Format

    Schema

    json

    { "type": "object", "properties": { "influencer": { "type": "object", "properties": { "{{username}}": { "type": "object", "description": "Influencer profile (see 'Influencer Show' Expect Responses for full property descriptions)", "properties": [ "uid", "name", "description", "primary_affiliation", "title", "is_brand", "location", "thumbnail_url", "avatar", "reach", "resonance", "audience" ] } } } } }

  • POSTInfluencer Add - Social/influencers/add/social
    Add an Influencer to the system via their Social username/ID. If the username/ID does not exist, then an HTTP status code of 404 will be returned.
    
    

    Parameter	Value	Type	Description
    username		string	Social username. Either username or user_id is required
    user_id		string	Social user ID. Either username or user_id is required
    platform	TWITTERINSTAGRAMTIKTOKFACEBOOK	enumerated	Social platform
    is_brand	truefalse	boolean	Indicates whether the username is associated to a brand (i.e. not a person)
    customer_key		string	The customer key associated with your account. Contact api-support@traackr.com to have one issued to you
    tags		string	Tag strings(s) to add to the profile, comma-separated. Tagged profiles can then be searched through these tags

    Expect Responses

    Format

    Schema

    json

    { "type": "object", "properties": { "influencer": { "type": "object", "properties": { "{{username|user_id}}": { "type": "object", "description": "Influencer profile (see 'Influencer Show' Expect Responses for full property descriptions)", "properties": [ "uid", "name", "description", "primary_affiliation", "title", "is_brand", "location", "thumbnail_url", "avatar", "reach", "resonance", "audience", "tags (requires customer_key)" ] } } } } }

  • GETInfluencer Connections - All/influencers/connections/:uid
    Returns a list of people connected to and from the influencer(s) requested
    
    

    Parameter	Value	Type	Description
    uid		string	Influencer UID(s). This can either be a single value or a comma-separated string of multiple UIDs (up to 100). If none of the UIDs are valid, then an HTTP status code of 404 will be returned.

    Expect Responses

    Format

    Schema

    json

    { "type": "object", "properties": { "influencer": { "type": "object", "properties": { "{{influencer-UID}}": { "type": "object", "properties": { "uid": { "type": "string", "description": "Influencer UID" }, "connections_to": { "type": "array", "optional": true, "description": "People whom this influencer is connected to", "items": { "type": "object", "properties": { "native_id": { "type": "string", "description": "The native id corresponding to the connection type" }, "type": { "type": "enumerated", "description": "User type by platform", "EnumeratedList": [ "TRAACKR", "TWITTER_USER" ] }, "connection_score": { "type": "integer", "description": "The raw connection score indicating how strong a connection between the influencer and the connection result" }, "connection_metrics": { "type": "object", "description": "Array of connection metrics" } } } }, "connections_from": { "type": "array", "optional": true, "description": "People whom this influencer is connected from", "items": { "type": "object", "properties": { "native_id": { "type": "string", "description": "The native id corresponding to the connection type" }, "type": { "type": "enumerated", "description": "User type by platform", "EnumeratedList": [ "TRAACKR", "TWITTER_USER" ] }, "connection_score": { "type": "integer", "description": "The raw connection score indicating how strong a connection between the influencer and the connection result" }, "connection_metrics": { "type": "object", "description": "Array of connection metrics" } } } } } } } } } }

  • GETInfluencer Connections - Directed/influencers/connections/:direction/:uid
    Returns a list of people connected to or from the influencer(s) requested
    
    

    Parameter	Value	Type	Description
    uid		string	Influencer UID(s). This can either be a single value or a comma-separated string of multiple UIDs (up to 100). If none of the UIDs are valid, then an HTTP status code of 404 will be returned.
    direction	tofrom	enumerated	Direction of connection. A value of "to" will bring back people the influencer is connected to, and the vice-versa for a value of "from".

    Expect Responses

    Format	Schema
    json	{ "description": "See 'Influencer Connections - All' Expect Responses" }

  • GET*Influencer Lookup/influencers/lookup
    Lookup influencers in the Traackr database using various filtering and sorting criteria.
    
    

    Parameter	Value	Type	Description
    tags		string	List of tag filters, comma-separated. Tags are ANDed together. Useful for filtering influencers to a targeted group of people. Use in conjunction with the /influencers/tag/add and /influencers/tag/remove endpoints to customize your influencer groups
    tags_exclusive		string	Tags to ignore during the lookup process, comma-separated. Useful for discovering influencers outside a particular 'tag' segment
    is_tag_prefix	truefalse	boolean	If true, the tag(s) will be utilized in a prefix search (e.g. searching 'foo' would return the union of influencers associated to tags 'foo/bar', 'foo/inc', etc.)
    influencers		string	Influencer UID(s) to restrict the lookup to, comma-separated (up to 500). Useful for surfacing influencers from a non-tagged group of people
    influencers_exclusive		string	Influencer UID(s) to ignore from the lookup, comma-separated (up to 500). Useful for excluding influencers from a tagged group of people
    type	personbrandall	enumerated	Filter to restrict influencers based on their type
    name		string	Filters to restrict an influencers to a specific name, comma-separated. Multiple filters are OR'ed together.
    gender	allmalefemale	enumerated	Filter to restrict an influencers to a specific gender
    emails		string	Filter to restrict influencers to a specific list of emails, comma-separated. Allows up to 100 emails to be used.
    iso_location		string	Filter to restrict influencers to a particular geo-location. Expected format is a JSON array of one-to-many geo-filter JSON objects. For example, if you wanted to find all influencers in the U.S. but not in Massachusetts, the geolocation JSON string would look like: "[ {"type":"INCLUSION", "fields":{"COUNTRY":"US"}}, {"type":"EXCLUSION", "fields":{"STATE":"US-MA"}}]". The supported fields within the "fields" object are [GEODIVISION, GEOSUBDIVISION, COUNTRY, STATE, COUNTY]. All values for [COUNTRY, STATE, COUNTY] should be ISO-3166 compliant (see http://en.wikipedia.org/wiki/ISO_3166-2). All values for [GEODIVISION, GEOSUBDIVISION] come from the UN M.49 standard (see http://en.wikipedia.org/wiki/UN_M.49) and should be prefixed with UN (e.g. for Americas, use value "UN019"
    text_location		string	Filter to restrict influencers to a particular location. This is a free form text filter that would match against a human readable address (e.g. Boston, MA)
    title		string	Filters to restrict influencers to those that contain specific words in their title, comma-separated. Multiple filters are OR'ed together.
    bio		string	Filters to restrict influencers to those that contain specific words in their bio, comma-separated. Multiple filters are OR'ed together.
    affiliation		string	Filters to restrict influencers to those that contain specific words in their affiliation, comma-separated. Multiple filters are OR'ed together.
    all_filter		string	A catch-all of comma-separated filters that operate against the following fields: name, title, bio, affiliation and text_location. Text matches against any of those fields will return the corresponding influencer records. Multiple filters are OR'ed together.
    is_verified	truefalse	enumerated	Filter to restrict influencers based on their Twitter verified status
    oauth_status		string	JSON string representing the OAuth status to filter on. Takes the format of {"platform":<platform>,"states":[<state>,...]}. Accepted platform values are ["INSTAGRAM"]. Accepted states are ["AUTHENTICATED", "EXPIRED", "UNAUTHENTICATED"]
    platform_audience		string	JSON string representing the platform 'audience' criteria to filter on. Takes the format of {"platform":<platform>,"minAudienceSize":<min>,"maxAudienceSize":<max>}. One of minAudienceSize or maxAudienceSize is required. Valid platforms are TWITTER, INSTAGRAM, YOUTUBE, FACEBOOK, TWITCH, PINTEREST, TIKTOK, and STACKOVERFLOW, but are subject to change over time
    platform_eng_rate		string	JSON string representing the platform 'engagement rate' criteria to filter on. Takes the format of {"platform":<platform>,"minEngRate":<min>,"maxEngRate":<max>}. One of minEngRate or maxEngRate is required. Valid platforms are TWITTER, INSTAGRAM, YOUTUBE, FACEBOOK, but are subject to change over time
    reach_min		double	Filter to restrict influencers based on a minimum reach threshold (inclusive). Expected value is of type Double where 0.01 <= val <= 1. Defaults to lower-bound
    reach_max		double	Filter to restrict influencers based on a maximum reach threshold (inclusive). Expected value is of type Double where 0.01 <= val <= 1. Defaults to upper-bound
    resonance_min		double	Filter to restrict influencers based on a minimum resonance threshold (inclusive). Expected value is of type Double where 0.01 <= val <= 1. Defaults to lower-bound
    resonance_max		double	Filter to restrict influencers based on a maximum resonance threshold (inclusive). Expected value is of type Double where 0.01 <= val <= 1. Defaults to upper-bound
    enable_tags_aggregation	truefalse	boolean	Include aggregated hit counts per influencer tag. Note: the 'tags' parameter must be provided for this aggregation to work.
    enable_country_aggregation	truefalse	boolean	Include aggregated influencer counts for country ISO code.
    enable_audience_aggregation	truefalse	boolean	Include estimated audience stats for the influencers matched by the lookup.
    count		integer	The number of results to return per page, up to a max of 100. Defaults to 25
    page		integer	The results page number. Defaults to 0. Max pageable results (page * count) for this call is set at 1000
    sort	namereachresonanceaudienceplatform_audience_trendfacebook_audiencefacebook_eng_ratefacebook_pages_fans_trendinstagram_audienceinstagram_eng_rateinstagram_followers_trendpinterest_audiencestackoverflow_audiencetiktok_audiencetiktok_eng_ratetiktok_followers_trendtwitch_audiencetwitch_followers_trendtwitter_audiencetwitter_eng_ratetwitter_followers_count_trendyoutube_audienceyoutube_eng_rateyoutube_subscribers_trend	enumerated	Indicates how influencer results will be sorted. Defaults to "name" if no value is provided
    sort_order	ascdesc	enumerated	Indicates the sort order of the results applied against the 'sort' parameter. Accepted sort order values are ["asc", "desc"]. Defaults to "asc" if no value is provided
    customer_key		string	Use when passing tag filters to limit results to the tag namespace for your account (passing tag filters without a customer key will return an API error). Multiple customer keys are supported via the comma-delimited syntax and are implictly OR'ed together. If you don't have a customer key, contact api-support@traackr.com to have one issued to you.
    report_id		string	If this parameter is specified, the lookup of influencers will occur in the active snapshot index associated with the report_id

    Expect Responses

    Format

    Schema

    json

    { "type": "object", "properties": { "page_info": { "type": "object", "properties": { "has_more": { "type": "boolean", "description": "Indicates whether there are more results based on pagination" }, "current_page": { "type": "integer", "description": "Indicates the current page number for the results" }, "next_page": { "type": "integer", "description": "Indicates the next page number for the results. A value of 0 indicates no next page" }, "page_count": { "type": "integer", "description": "The requested number of results per page" }, "results_count": { "type": "integer", "description": "The actual number of results on the page" }, "total_results_count": { "type": "integer", "description": "The total number of results matching the search, irrespective of pagination (capped at 10k)" } } }, "influencers": { "type": "array", "description": "Influencer lookup results", "items": { "type": "object", "description": "Influencer profile (see 'Influencer Show' Expect Responses for full property descriptions)", "properties": [ "uid", "name", "description", "primary_affiliation", "title", "is_brand", "location", "thumbnail_url", "avatar", "reach", "resonance", "audience" ] } }, "aggregations": { "type": "object", "properties": { "<aggregation name 1>": { "type": "object", "description": "Name of the aggregated counts", "properties": { "buckets": { "type": "array", "optional": true, "description": "The aggregation buckets", "items": { "type": "object", "properties": { "key": { "type": "string or long", "optional": false, "description": "The key for the bucket, string by default, long if it's a date histogram bucket" }, "key_as_string": { "type": "string", "optional": true, "description": "For date histogram buckets, the key as a date string representation" }, "count": { "type": "long", "optional": false, "description": "The count of records that matched the bucket" } } } }, "value": { "type": "long", "optional": true, "description": "Value from aggregations that return single numbers" }, "count": { "type": "long", "optional": true, "description": "For stats aggregations, the count of records that contributed to the stats" }, "min": { "type": "double", "optional": true, "description": "For stats aggregations, the min value that contributed to the stats" }, "max": { "type": "double", "optional": true, "description": "For stats aggregations, the max value that contributed to the stats" }, "avg": { "type": "double", "optional": true, "description": "For stats aggregations, the average of the values that contributed to the stats" }, "sum": { "type": "double", "optional": true, "description": "For stats aggregations, the sum of the values that contributed to the stats" } } }, "<aggregation name 2>": { "type": "object", "description": "Next aggregation if applicable..." } } } } }

  • GETInfluencer Lookup - Social/influencers/lookup/social/:identifier
    Lookup an Influencer profile by the requested Social username/ID. If no profile can be found, then an HTTP status code of 404 will be returned.
    
    

    Parameter	Value	Type	Description
    platform	TWITTERINSTAGRAMTIKTOKFACEBOOK	enumerated	Social platform
    identifier		string	Social username/ID
    type	USERNAMEUSER_ID	enumerated	Flag whether identifier is a username or ID
    customer_key		string	The customer key associated with your account

    Expect Responses

    Format

    Schema

    json

    { "type": "object", "properties": { "influencer": { "type": "object", "properties": { "{{username|user_id}}": { "type": "object", "description": "Influencer profile (see 'Influencer Show' Expect Responses for full property descriptions)", "properties": [ "uid", "name", "description", "primary_affiliation", "title", "is_brand", "location", "thumbnail_url", "avatar", "reach", "resonance", "audience", "tags (requires customer_key)" ] } } } } }

  • GET*Influencer Search/influencers/search
    Searches for the top-ranked influencers for a particular set of keywords and/or audience criteria (at least one is required). Influencers are ranked based on a scoring algorithm involving their reach, resonance, and relevance. To learn more about Traackr's three R's, see https://traackr.zendesk.com/entries/23297467-What-do-Reach-Resonance-Relevance-mean-
    
    

    Parameter	Value	Type	Description
    audience		string	JSON string representing the audience criteria to match on. Takes the format of {"filters":[ {"code":"<code>"}] }. Required if `keywords` parameter is not provided. For the complete list of audience search codes and advanced usage examples, please reach out to api-support@traackr.comy. This feature is only available for Premium API customers
    keywords		string	Keyword(s) to search on, comma-separated. See general guidelines above for usage. Required if `audience` parameter is not provided
    exclusion_keywords		string	Keyword(s) to exclude on, comma-separated. The keyword types defined above apply here as well
    tags		string	List of tag filters, comma-separated. Tags are ANDed together. Useful for filtering influencers to a targeted group of people. Use in conjunction with the /influencers/tag/add and /influencers/tag/remove endpoints to customize your influencer groups
    tags_exclusive		string	Tags to ignore during the search process, comma-separated. Useful for discovering influencers outside a particular 'tag' segment
    is_tag_prefix	truefalse	boolean	If true, the tag(s) will be utilized in a prefix search (e.g. searching 'foo' would return the union of influencers associated to tags 'foo/bar', 'foo/inc', etc.)
    influencers		string	Influencer UID(s) to restrict the search to, comma-separated (up to 500). Useful for surfacing influencers from a non-tagged group of people
    influencers_exclusive		string	Influencer UID(s) to exclude from the search, comma-separated (up to 500). Useful for excluding influencers from the result set
    channels		string	Channel UID(s) to restrict the search to, comma-separated (up to 500)
    channels_exclusive		string	Channel UID(s) to exclude from the search, comma-separated (up to 500)
    posts_inclusive		string	Post UID(s) to restrict the search to, comma-separated (up to 500)
    posts_exclusive		string	Post UID(s) to exclude from the search, comma-separated (up to 500)
    since_when		string	Only results with a published date greater than this timestamp will be returned. Expected date input format: YYYY-MM-DD'T'hh:mm:ssZ (e.g. 2012-06-30T13:30:00-0400).
    max_when		string	Only results with a published date less than this timestamp will be returned. Expected date input format: YYYY-MM-DD'T'hh:mm:ssZ (e.g. 2012-06-30T13:30:00-0400)
    root_urls_inclusive		string	Filter to restrict an influencer's relevant posts to those belonging to the specified root urls, comma-separated. Sub-domains are not supported
    root_urls_exclusive		string	Filter to restrict an influencer's relevant posts to those NOT belonging to the specified root urls, comma-separated. Sub-domains are not supported
    publication_types_inclusive	STORYSTREAM	enumerated	Filter to restrict posts by specific publication type(s) (comma-separated). Useful in combination with `root_urls_inclusive` parameter; e.g. to narrow down results to Instagram Stories, set publication_type_inclusive=STORY and root_urls_inclusive=instagram
    publication_types_exclusive	STORYSTREAM	enumerated	Filter to restrict posts by specific publication type(s) (comma-separated). Useful in combination with `root_urls_inclusive` parameter; e.g. to narrow down results to Instagram content except for Stories, set publication_type_exclusive=STORY and root_urls_inclusive=instagram
    include_shared_content	truefalse	boolean	Flag whether to include shared content (e.g. retweets) as part of the relevance scoring. Shared content is weighed less than original content in scoring.
    type	personbrandall	enumerated	Filter to restrict influencers based on their type
    name		string	Filters to restrict an influencers to a specific name, comma-separated. Multiple filters are OR'ed together.
    gender	allmalefemale	enumerated	Filter to restrict an influencers to a specific gender
    emails		string	Filter to restrict influencers to a specific list of emails, comma-separated. Allows up to 100 emails to be used.
    iso_location		string	Filter to restrict influencers to a particular geo-location. Expected format is a JSON array of one-to-many geo-filter JSON objects. For example, if you wanted to find all influencers in the U.S. but not in Massachusetts, the geolocation JSON string would look like: "[ {"type":"INCLUSION", "fields":{"COUNTRY":"US"}}, {"type":"EXCLUSION", "fields":{"STATE":"US-MA"}}]". The supported fields within the "fields" object are [GEODIVISION, GEOSUBDIVISION, COUNTRY, STATE, COUNTY]. All values for [COUNTRY, STATE, COUNTY] should be ISO-3166 compliant (see http://en.wikipedia.org/wiki/ISO_3166-2). All values for [GEODIVISION, GEOSUBDIVISION] come from the UN M.49 standard (see http://en.wikipedia.org/wiki/UN_M.49) and should be prefixed with UN (e.g. for Americas, use value "UN019"
    text_location		string	Filter to restrict influencers to a particular location. This is a free form text filter that would match against a human readable address (e.g. Boston, MA)
    lang	allardadeenelesfifriditjakonlnoplptrusvtrtl	enumerated	Filter to restrict an influencer's relevant posts to the specified language
    title		string	Filters to restrict influencers to those that contain specific words in their title, comma-separated. Multiple filters are OR'ed together.
    bio		string	Filters to restrict influencers to those that contain specific words in their bio, comma-separated. Multiple filters are OR'ed together.
    affiliation		string	Filters to restrict influencers to those that contain specific words in their affiliation, comma-separated. Multiple filters are OR'ed together.
    all_filter		string	A catch-all of comma-separated filters that operates against the following fields: name, title, bio, affiliation and text_location. Text matches against any of those fields will return the corresponding influencer records. Multiple filters are OR'ed together.
    is_verified	truefalse	enumerated	Filter to restrict influencers based on their Twitter verified status
    oauth_status		string	JSON string representing the OAuth status to filter on. Takes the format of {"platform":<platform>,"states":[<state>,...]}. Accepted platform values are ["INSTAGRAM"]. Accepted states are ["AUTHENTICATED", "EXPIRED", "UNAUTHENTICATED"]
    platform_audience		string	JSON string representing the platform 'audience' criteria to filter on. Takes the format of {"platform":<platform>,"minAudienceSize":<min>,"maxAudienceSize":<max>}. One of minAudienceSize or maxAudienceSize is required. Valid platforms are TWITTER, INSTAGRAM, YOUTUBE, FACEBOOK, TWITCH, PINTEREST, TIKTOK, and STACKOVERFLOW, but are subject to change over time
    platform_eng_rate		string	JSON string representing the platform 'engagement rate' criteria to filter on. Takes the format of {"platform":<platform>,"minEngRate":<min>,"maxEngRate":<max>}. One of minEngRate or maxEngRate is required. Valid platforms are TWITTER, INSTAGRAM, YOUTUBE, FACEBOOK, but are subject to change over time
    reach_min		double	Filter to restrict influencers based on a minimum reach threshold (inclusive). Expected value is of type Double where 0.01 <= val <= 1. Defaults to lower-bound
    reach_max		double	Filter to restrict influencers based on a maximum reach threshold (inclusive). Expected value is of type Double where 0.01 <= val <= 1. Defaults to upper-bound
    resonance_min		double	Filter to restrict influencers based on a minimum resonance threshold (inclusive). Expected value is of type Double where 0.01 <= val <= 1. Defaults to lower-bound
    resonance_max		double	Filter to restrict influencers based on a maximum resonance threshold (inclusive). Expected value is of type Double where 0.01 <= val <= 1. Defaults to upper-bound
    relevance_min		double	Filter to restrict influencers based on a minimum relevance threshold (inclusive). Expected value is of type Double where 0 <= val <= 1. Setting the threshold to zero will include influencers with fractional relevance. Defaults to 0.01
    enable_audience_aggregation	truefalse	boolean	Include estimated audience stats for the content matched by the search.
    enable_country_aggregation	truefalse	boolean	Include aggregated influencer counts for country ISO code.
    count		integer	The number of results to return per page, up to a max of 100. Defaults to 25
    page		integer	The results page number. Defaults to 0. Max pageable results (page * count) for this call is set at 1000
    sort	relevancenamereachresonanceaudienceplatform_audience_trendfacebook_audiencefacebook_eng_ratefacebook_pages_fans_trendinstagram_audienceinstagram_eng_rateinstagram_followers_trendpinterest_audiencestackoverflow_audiencetiktok_audiencetiktok_eng_ratetiktok_followers_trendtwitch_audiencetwitch_followers_trendtwitter_audiencetwitter_eng_ratetwitter_followers_count_trendyoutube_audienceyoutube_eng_rateyoutube_subscribers_trend	enumerated	Sort parameter to override the natural ordering of influencer results based on the search's scoring mode. Defaults to "relevance" if no value is provided
    sort_order	ascdesc	enumerated	Indicates the sort order of the results applied against the 'sort' parameter. Accepted sort order values are ["asc", "desc"]. Defaults to "desc" if no value is provided
    scoring_mode	traackrhit_countactualized_reachavg_engagementengagement_rateengagement_rate_v2commentsestimated_impressionsimpressionspotential_reachreactionssharestotal_engagementvideo_views	enumerated	The scoring mode that determines how influencers are scored and ranked. Each scoring mode defines relevance differently, so influencer relevance values between modes are not comparable. Defaults to "traackr" (i.e. traackr's keyword relevance algorithm) if no value is provided. Scoring by `engagement_rate_v2` is limited to the top 100.
    customer_key		string	Use when passing tag filters to limit results to the tag namespace for your account (passing tag filters without a customer key will return an API error). Multiple customer keys are supported via the comma-delimited syntax and are implictly OR'ed together. If you don't have a customer key, contact api-support@traackr.com to have one issued to you.
    report_id		string	If this parameter is specified, the influencers search will occur in the active snapshot index associated with the report_id

    Expect Responses

    Format

    Schema

    json

    { "type": "object", "properties": { "page_info": { "type": "object", "properties": { "has_more": { "type": "boolean", "description": "Indicates whether there are more results based on pagination" }, "current_page": { "type": "integer", "description": "Indicates the current page number for the results" }, "next_page": { "type": "integer", "description": "Indicates the next page number for the results. A value of 0 indicates no next page" }, "page_count": { "type": "integer", "description": "The requested number of results per page" }, "results_count": { "type": "integer", "description": "The actual number of results on the page" }, "total_results_count": { "type": "integer", "description": "The total number of results matching the search, irrespective of pagination (capped at 10k)" } } }, "influencers": { "type": "array", "description": "Influencer search results", "items": { "type": "object", "description": "Influencer profile (see 'Influencer Show' Expect Responses for full property descriptions). Relevance values are tied to the scoring mode used to run the search (default to traack's keyword scoring algorithm)", "properties": [ "uid", "name", "description", "primary_affiliation", "title", "is_brand", "location", "thumbnail_url", "avatar", "reach", "resonance", "audience", "relevance" ] } }, "aggregations": { "type": "object", "properties": { "<aggregation name 1>": { "type": "object", "description": "Name of the aggregated counts", "properties": { "buckets": { "type": "array", "optional": true, "description": "The aggregation buckets", "items": { "type": "object", "properties": { "key": { "type": "string or long", "optional": false, "description": "The key for the bucket, string by default, long if it's a date histogram bucket" }, "key_as_string": { "type": "string", "optional": true, "description": "For date histogram buckets, the key as a date string representation" }, "count": { "type": "long", "optional": false, "description": "The count of records that matched the bucket" } } } }, "value": { "type": "long", "optional": true, "description": "Value from aggregations that return single numbers" }, "count": { "type": "long", "optional": true, "description": "For stats aggregations, the count of records that contributed to the stats" }, "min": { "type": "double", "optional": true, "description": "For stats aggregations, the min value that contributed to the stats" }, "max": { "type": "double", "optional": true, "description": "For stats aggregations, the max value that contributed to the stats" }, "avg": { "type": "double", "optional": true, "description": "For stats aggregations, the average of the values that contributed to the stats" }, "sum": { "type": "double", "optional": true, "description": "For stats aggregations, the sum of the values that contributed to the stats" } } }, "<aggregation name 2>": { "type": "object", "description": "Next aggregation if applicable..." } } } } }

  • GETInfluencer Show/influencers/show/:uid
    Returns a variety of information about the influencer(s) requested
    
    

    Parameter	Value	Type	Description
    uid		string	Influencer UID(s). This can either be a single value or a comma-separated string of multiple UIDs (up to 100). If none of the UIDs are valid, then an HTTP status code of 404 will be returned.
    with_channels		Boolean	Whether to include a list of the influencer's channels (i.e. social footprint) in the response
    with_audience		Boolean	Whether to include audience analysis data on the influencer's channels (setting this to `true` will automatically include the influencer's channels in the response). This feature is only available for Premium API customers
    with_historical_data		Boolean	Whether to include historical data, such as the influencer's social metrics history
    customer_key		string	If a valid customer key is provided, then account-specific information (e.g. tags) is returned in the influencer response
    tags_from_accts		string	Comma-separated string of other customer keys. Results in additional account information (e.g. additional tags) being returned in the influencer response. These tags are prefixed by their respective customer keys so as to distinguish which account they belong to.

    Expect Responses

    Format

    Schema

    json

    { "type": "object", "properties": { "influencer": { "type": "object", "properties": { "{{influencer-UID}}": { "type": "object", "properties": { "uid": { "type": "string", "description": "Influencer UID" }, "is_reviewed": { "type": "boolean", "description": "Whether the influencer has been internally reviewed by Traackr" }, "name": { "type": "string", "description": "Influencer Name" }, "description": { "type": "string", "description": "Influencer Bio" }, "primary_affiliation": { "type": "string", "description": "Influencer Primary Affiliation (e.g. company, organization, etc.)" }, "title": { "type": "string", "description": "Influencer Title (e.g. CFO)" }, "is_brand": { "type": "boolean", "description": "Whether the influencer is a brand" }, "verified": { "type": "boolean", "description": "Twitter verified status derived from the Influencer's sole ownership Twitter channels" }, "location": { "type": "string", "description": "Influencer Location text" }, "iso_location": { "type": "object", "description": "Influencer Location ISO codes and geographic coordinates", "properties": { "neighborhood": { "type": "string", "description": "A political or geographic subdivison of a city. (i.e. Greenwich Village is a neighborhood of New York, NY)" }, "city": { "type": "string", "description": "A town or municipality" }, "county": { "type": "string", "description": "A geopolitical subdivision of a state or province. Also known as an administrative area level 2. (i.e. Suffolk County is where the city of Boston is located)" }, "countyISO": { "type": "string", "description": "The ISO-3166-2 code associated with a county" }, "stateProvince": { "type": "string", "description": "A geopolitical subdivision of a country. Also known as an administrative area level1. (i.e. California is a State in the United States of America)" }, "stateProvinceISO": { "type": "string", "description": "The ISO-3166-2 code associated with a state or province" }, "country": { "type": "string", "description": "A nation with its own government occupying a territory" }, "countryISO": { "type": "string", "description": "The ISO-3166 code associated with a country" }, "postalCode": { "type": "string", "description": "The country's' zip or postal code" }, "location": { "type": "string", "description": "A free-text description of the influencer's location" }, "latitude": { "type": "double", "description": "Latitude" }, "longitude": { "type": "double", "description": "Longitude" }, "radiusMeters": { "type": "double", "description": "A rough estimate, the average radius in meters from the specified latitude longitude, that would cover the area of the region specified" }, "geoDivision": { "type": "string", "description": "A macro geographical region, or continental region (i.e. Europe or Africa)" }, "geoDivisionUN49": { "type": "string", "description": "The UN M49 Code associated with the Geo Division (https://unstats.un.org/unsd/methods/m49/m49regin.htm)" }, "geoSubdivision": { "type": "string", "description": "A geographical subdivision of the region described above (i.e. Western Europe or Eastern Africa)" }, "geoSubdivisionUN49": { "type": "string", "description": "The UN M49 Code associated with the Geo Sub-Division (https://unstats.un.org/unsd/methods/m49/m49regin.htm)" } } }, "email": { "type": "string", "description": "Influencer Email address" }, "gender": { "type": "string", "description": "Influencer Gender (male, female)" }, "thumbnail_url": { "type": "string", "description": "(Deprecated) Influencer Thumbnail Image URL" }, "avatar": { "type": "object", "description": "Influencer Profile Image URL(s)", "properties": { "large": { "type": "string", "description": "Best determination for this influencer's large-sized Image URL (200px+ width)" }, "medium": { "type": "string", "description": "Best determination for this influencer's medium-sized Image URL (70-100px width)" }, "small": { "type": "string", "description": "Best determination for this influencer's small-sized Image URL (<50px width)" } } }, "reach": { "type": "string", "description": "Influencer Reach" }, "resonance": { "type": "string", "description": "Influencer Resonance" }, "audience": { "type": "string", "description": "Influencer Audience" }, "aliases": { "type": "array", "description": "Known alias UIDs that reference this influencer. These aliases expire after 6 months so it's important to update any influencer references you might store to reference the primary influencer UID.", "optional": true }, "tags": { "type": "array", "description": "Customer Account tags assigned to this influencer (requires customer_key)", "optional": true }, "other_tags": { "type": "array", "description": "Other Customer Account tags assigned to this influencer (see tags_from_accts parameter)", "optional": true }, "channels": { "type": "array", "optional": true, "items": { "type": "object", "properties": { "uid": { "type": "string", "description": "Channel UID" }, "url": { "type": "string", "description": "Channel URL" }, "root_domain": { "type": "string", "description": "Channel Root Domain" }, "platform_id": { "type": "string", "description": "External Platform Id (only applies for major platforms like Twitter, Instagram, Youtube, Facebook, etc.)", "optional": true }, "username": { "type": "string", "description": "Platform user handle (applicable only for Twitter)", "optional": true }, "ownership": { "type": "string", "description": "Influencer ownership level in regard to the channel. Either owner, contributor, or reference" }, "metrics": { "type": "array", "description": "Channel Metrics List. All values, even numeric, are returned as strings. Please use care when casting them.", "items": { "type": "object", "properties": { "m_id": "Metric Id", "m_name": "Metric Display Name", "m_value": "Metric Value" } } }, "metrics_history": { "type": "array", "description": "Historical Channel Metrics List (only included when `with_historical_data` is set to true)", "items": { "type": "object", "properties": { "date": "Metrics capture date (YYYY-MM-DD)", "metrics": { "type": "object", "properties": { "m_id": "Metric Id", "m_name": "Metric Display Name", "m_value": "Metric Value" } } } } }, "trends": { "type": "object", "description": "Channel Trends data that is calculated via snapshots of the channel's metrics values from the previous five weeks. Only applicable the following platforms (trend_id in parenthesis): Instagram (instagram_followers), Facebook (facebook_pages_fans), Twitter (twitter_followers_count), and Youtube (youtube_subscribers)", "properties": { "": { "type": "object", "properties": { "net": { "type": "double", "description": "Raw difference between previous & current trend values" }, "percent": { "type": "double", "description": "Percent difference between previous & current trend values" }, "current": { "type": "double", "description": "Current trend value" }, "previous": { "type": "double", "description": "Previous trend value" } } } } }, "platform_data": { "type": "object", "description": "Aggregated Influencer platform data", "properties": { "": { "type": "object", "properties": { "audience_sum": { "type": "long", "description": "Sum of all audience sizes for the parent platform", "optional": true }, "eng_rate_max": { "type": "double", "description": "Max engagement rate for the parent platform", "optional": true } } } } } } } } } } } } } }

  • POSTInfluencer Tags - Add/influencers/tag/add
    Tag influencer profiles with one or more strings. These tags belong to a unique namespace associated with your account via a customer key. If you don't have a customer key, contact api-support@traackr.com to have one issued to you
    
    

    Parameter	Value	Type	Description
    influencers		string	Influencer UID(s) whose profiles will be tagged, comma-separated
    tags		string	Tag strings(s) to add to profiles, comma-separated. Tagged profiles can then be searched through these tags
    customer_key		string	The customer key name space with which the tags will be associated
    strict	truefalse	boolean	If true, these tags will be removed from any Traackr profiles that are not included in the list of influencer UID(s) passed through this call. This is a good way to ensure that only the ids passed are tagged

    Expect Responses

    Format	Schema
    json	{ "type": "object", "properties": { "status": { "type": "string", "description": "Operation status. Expect 'ok' if successful" } } }

  • POSTInfluencer Tags - Remove/influencers/tag/remove
    Remove one or more tags from influencer profiles. These tags belong to a unique namespace associated with your account via a customer key. If you don't have a customer key, contact api-support@traackr.com to have one issued to you
    
    

    Parameter	Value	Type	Description
    influencers		string	Influencer UID(s) whose profiles will be un-tagged, comma-separated. If no UID(s) are passed then the 'all' parameter needs to be set to 'true'
    tags		string	Tag strings(s) to remove from the profiles, comma-separated
    customer_key		string	The customer key name space with which the tags are associated
    all	truefalse	boolean	If true, the list of influencer UID(s) will be ignored and the specified tags will be removed from all Traackr profiles

    Expect Responses

    Format	Schema
    json	{ "type": "object", "properties": { "status": { "type": "string", "description": "Operation status. Expect 'ok' if successful" } } }

  • POSTInfluencer Tags - Bulk Edit/influencers/tag/bulkedit
    Bulk add and/or remove tags for influencer profiles. These tags belong to a unique namespace associated with your account via a customer key. If you don't have a customer key, contact api-support@traackr.com to have one issued to you
    
    

    Parameter	Value	Type	Description
    influencers		string	Influencer UID(s) whose profiles will be tagged, comma-separated
    tags_add		string	Tag strings(s) to add to profiles, comma-separated. Tagged profiles can then be searched through these tags
    tags_remove		string	Tag strings(s) to remove from the profiles, comma-separated
    customer_key		string	The customer key name space with which the tags will be associated

    Expect Responses

    Format	Schema
    json	{ "type": "object", "properties": { "status": { "type": "string", "description": "Operation status. Expect 'ok' if successful" } } }

  • GETInfluencer Tags - List/influencers/tag/list
    Lists the UID(s) of the influencer profiles associated with a given tag. This tag belongs to a unique namespace associated with your account via a customer key. If you don't have a customer key, contact api-support@traackr.com to have one issued to you
    
    

    Parameter	Value	Type	Description
    tag		string	The tag with which to look up associated profiles
    is_prefix	truefalse	boolean	If true, the tag will be utilized in a prefix search (e.g. searching 'foo' would return the union of influencer UIDs associated to tags 'foo/bar', 'foo/inc', etc.)
    type	personbrandall	enumerated	Filter to restrict influencers based on their type
    customer_key		string	The customer key name space with which the tags are associated

    Expect Responses

    Format	Schema
    json	{ "type": "object", "properties": { "influencers": { "type": "array", "optional": false, "description": "The list of UID(s) whose profiles match the tag", "items": { "type": "string" } } } }

  • POSTInfluencer Channels - Add/influencers/channels/add
    Add a channel to an influencer via a URL. Adding the same channel several times will have no additional effect.
    
    

    Parameter	Value	Type	Description
    influencer		string	Influencer UID.
    url		string	Channel's URL (e.g. blog or website)
    ownership	ownercontributorreference	enumerated	The influencer's level of ownership of this channel. 'owner' will assign them 100% of the metrics, contributor will attempt a best guess based on RSS feed stats (if applicable) or default to 33%, 'reference' will not assign any metrics.

    Expect Responses

    Format	Schema
    json	{ "type": "object", "description": "Channel profile (see 'Influencer Show' Expect Responses for full property descriptions). The only supplementary field in the response is 'influencer_uid' to indicate the parent Influencer", "properties": [ "uid", "url", "metrics", "trends", "ownership", "root_domain", "platform_id", "username", "influencer_uid" ] }

  • POSTInfluencer Report/influencers/report
    Report an influencer's channel (e.g. spam). Reporting the same influencer and channel several times will have no additional effect.
    
    

    Parameter	Value	Type	Description
    influencer		string	Influencer UID.
    url		string	Channel's URL (e.g. blog or website)
    reportText		string	Short description of the reason for the report.

    Expect Responses

    Format	Schema
    json	{ "type": "object", "properties": { "influencer_uid": { "type": "string", "description": "The UID of the influencer that was reported." }, "url": { "type": "string", "description": "The URL of the channel that was reported." }, "reportText": { "type": "string", "description": "The description of the issue that was reported." } } }

• Posts

  • List Methods
  • Expand Methods

  • GET*Post Lookup/posts/lookup
    Lookup posts for a particular set of influencers (specified with either an 'influencers' or 'tags' parameter). Supports a variety of filters, aggregations, and sorts. In addition, the posts' assigned influencers can be included in the response by setting include_entities=true
    
    

    Parameter	Value	Type	Description
    tags		string	List of tag filters, comma-separated. Tags are ANDed together. Useful for filtering influencers to a targeted group of people. Use in conjunction with the /influencers/tag/add and /influencers/tag/remove endpoints to customize your influencer groups
    tags_exclusive		string	Tags to ignore during the lookup process, comma-separated. Useful for discovering influencers outside a particular 'tag' segment
    is_tag_prefix	truefalse	boolean	If true, the tag(s) will be utilized in a prefix search (e.g. searching 'foo' would return the union of posts whose influencers are associated to tags 'foo/bar', 'foo/inc', etc.)
    influencers		string	Influencer UID(s) to restrict the lookup to, comma-separated (up to 500). Useful for surfacing content for a non-tagged group of people
    influencers_exclusive		string	Influencer UID(s) to exclude from the search, comma-separated (up to 500). Useful for excluding content for specific influencers
    channels		string	Channel UID(s) to restrict the search to, comma-separated (up to 500)
    channels_exclusive		string	Channel UID(s) to exclude from the search, comma-separated (up to 500)
    posts_inclusive		string	Post UID(s) to restrict the search to, comma-separated (up to 500)
    posts_exclusive		string	Post UID(s) to exclude from the search, comma-separated (up to 500)
    since_when		string	Only results with a published date greater than this timestamp will be returned. Expected date input format: YYYY-MM-DD'T'hh:mm:ssZ (e.g. 2012-06-30T13:30:00-0400)
    max_when		string	Only results with a published date less than this timestamp will be returned. Expected date input format: YYYY-MM-DD'T'hh:mm:ssZ (e.g. 2012-06-30T13:30:00-0400)
    since_id		string	Only results published after than the specified post UID will be returned
    max_id		string	Only results published before than the specified post UID will be returned
    root_urls_inclusive		string	Filter to restrict the post lookup to only those posts belonging to the specified root urls, comma-separated. Sub-domains are not supported
    root_urls_exclusive		string	Filter to restrict the post lookup to only those posts NOT belonging to the specified root urls, comma-separated. Sub-domains are not supported
    lang	allardadeenelesfifriditjakonlnoplptrusvtrtl	enumerated	Filter to restrict posts to the specified language
    include_brand_content	truefalse	boolean	Flag whether to include brand content as part of the post lookup
    include_shared_content	truefalse	boolean	Flag whether to include shared content (e.g. retweets) as part of the post lookup
    has_engagement	truefalse	enumerated	Filter to restrict posts to those that do -or- do not have engagement
    publication_types_inclusive	STORYSTREAM	enumerated	Filter to restrict posts by specific publication type(s) (comma-separated). Useful in combination with `root_urls_inclusive` parameter; e.g. to narrow down results to Instagram Stories, set publication_type_inclusive=STORY and root_urls_inclusive=instagram
    publication_types_exclusive	STORYSTREAM	enumerated	Filter to restrict posts by specific publication type(s) (comma-separated). Useful in combination with `root_urls_inclusive` parameter; e.g. to narrow down results to Instagram content except for Stories, set publication_type_exclusive=STORY and root_urls_inclusive=instagram
    influencer_name		string	Filter to restrict posts authored by influencers with a specific name
    influencer_gender	allmalefemale	enumerated	Filter to restrict posts authored by influencers with a specific gender
    influencer_emails		string	Filter to restrict posts authored by influencers with a specific email. Allows up to 100 emails to be used at once, comma-separated
    influencer_iso_location		string	Filter to restrict posts authored by influencers with a particular geo-location. Expected format is a JSON array of one-to-many geo-filter JSON objects. For example, if you wanted to find all influencers in the U.S. but not in Massachusetts, the geolocation JSON string would look like: "[ {"type":"INCLUSION", "fields":{"COUNTRY":"US"}}, {"type":"EXCLUSION", "fields":{"STATE":"US-MA"}}]". The supported fields within the "fields" object are [GEODIVISION, GEOSUBDIVISION, COUNTRY, STATE, COUNTY]. All values for [COUNTRY, STATE, COUNTY] should be ISO-3166 compliant (see http://en.wikipedia.org/wiki/ISO_3166-2). All values for [GEODIVISION, GEOSUBDIVISION] come from the UN M.49 standard (see http://en.wikipedia.org/wiki/UN_M.49) and should be prefixed with UN (e.g. for Americas, use value "UN019"
    influencer_title		string	Filter to restrict posts authored by influencers that contain specific words in their title, comma-separated.
    influencer_bio		string	Filter to restrict posts authored by influencers that contain specific words in their bio, comma-separated.
    influencer_affiliation		string	Filter to restrict posts authored by influencers that contain specific words in their affiliation, comma-separated.
    influencer_all_filter		string	Filter to restrict posts authored by influencers that contain specific words in either their name, title, bio, affiliation or text_location. Operates as a catch-all influencer filter
    influencer_is_verified	truefalse	enumerated	Filter to restrict posts authored by influencers with a specific Twitter verified status
    influencer_reach_min		double	Filter to restrict posts authored by influencers within a minimum reach threshold (inclusive). Expected value is of type Double where 0.01 <= val <= 1. Defaults to lower-bound
    influencer_reach_max		double	Filter to restrict posts authored by influencers within a maximum reach threshold (inclusive). Expected value is of type Double where 0.01 <= val <= 1. Defaults to upper-bound
    influencer_resonance_min		double	Filter to restrict posts authored by influencers within a minimum resonance threshold (inclusive). Expected value is of type Double where 0.01 <= val <= 1. Defaults to lower-bound
    influencer_resonance_max		double	Filter to restrict posts authored by influencers within a maximum resonance threshold (inclusive). Expected value is of type Double where 0.01 <= val <= 1. Defaults to upper-bound
    include_entities	truefalse	boolean	Flag whether to include influencer entities in the response
    aggregations		string	JSON string representing a set of enabled aggregations referenced by their name (accepted values - `agg_influencers`, `agg_domains`, `agg_hashtags`, `agg_publication_types`, `agg_links`, `agg_monthly`, `agg_weekly`, `agg_daily`, `agg_metrics`, `agg_engagement`, `agg_engagement_rate`, `agg_comments`, `agg_estimated_impressions`, `agg_impressions`, `agg_reactions`, `agg_shares`, `agg_video_views`, `agg_story_views`, `agg_actualized_reach`, `agg_potential_reach`). An aggregation value can either be a boolean (true to enable) or a child JSON structure defining a sub-aggregation or additional params. E.g. {"agg_keyword":{"agg_influencers":true},"agg_domains":{"size":25},"agg_hashtags":{"size":0,"distinct_count":true}}. Top-level aggregations provide analytics over the original search result-set, while sub-aggregations provide analytics scoped to their parent `bucket`. All aggregations are `bucket` aggregations that return `n` buckets with aggregated counts, except for aggregations around engagement and metrics that return statistical values (sum, avg., etc.). The caller can use the `size` param to modify how many buckets are returned (which may impact performance) and also use `distinct_count` to produce a metric aggregation with estimated total `bucket` count (use `size:0` along with `distinct_count:true` for better performance if `bucket` count is only required). Certain params are not supported by all aggregations and may throw errors.
    aggregation_timezone		string	The time zone under which to compute any date related bucketing / aggregations. Please refer to http://joda-time.sourceforge.net/timezones.html for accepted offsets or canonical ids (e.g. both -05:00 and America/New_York are acceptable).
    sort	dateengagement_ratepotential_reachtotal_engagementstotal_commentstotal_estimated_impressionstotal_impressionstotal_reactionstotal_sharestotal_video_viewstotal_actualized_reach	enumerated	Indicates how post matches will be sorted. Accepted sort values are ["date", "potential_reach", "engagement_rate", "total_engagements", "total_comments", "total_impressions", "total_reactions", "total_shares", "total_video_views", "total_actualized_reach"]. Defaults to "date" if no value is provided
    sort_order	ascdesc	enumerated	Indicates the sort order of the results applied against the 'sort' parameter. Accepted sort order values are ["asc", "desc"]. Defaults to "desc" if no value is provided
    count		integer	The number of results to return per page, up to a max of 100. Defaults to 25
    page		integer	The results page number. Defaults to 0. Max pageable results (page * count) for this call is set at 2500
    customer_key		string	Use when passing tag filters to limit results to the tag namespace for your account (passing tag filters without a customer key will return an API error). Multiple customer keys are supported via the comma-delimited syntax and are implictly OR'ed together. If you don't have a customer key, contact api-support@traackr.com to have one issued to you.
    report_id		string	If this parameter is specified, the lookup of influencers will occur in the active snapshot index associated with the report_id

    Expect Responses

    Format

    Schema

    json

    { "type": "object", "properties": { "page_info": { "type": "object", "properties": { "has_more": { "type": "boolean", "description": "Indicates whether there are more results based on pagination" }, "current_page": { "type": "integer", "description": "Indicates the current page number for the results" }, "next_page": { "type": "integer", "description": "Indicates the next page number for the results. A value of 0 indicates no next page" }, "page_count": { "type": "integer", "description": "The requested number of results per page" }, "results_count": { "type": "integer", "description": "The actual number of results on the page" }, "total_results_count": { "type": "integer", "description": "The total number of results matching the search, irrespective of pagination (capped at 50k)" } } }, "posts": { "type": "array", "description": "Post lookup results", "items": { "type": "object", "properties": { "uid": { "type": "string", "description": "Post UID" }, "url": { "type": "string", "description": "Post URL" }, "root_domain": { "type": "string", "description": "Post Root Domain" }, "title": { "type": "string", "description": "Post Title" }, "truncated": { "type": "string", "optional": true, "description": "Indicates whether the post title is truncated (max of 200 chars)" }, "published_date": { "type": "string", "description": "Post Published Date" }, "author": { "type": "string", "description": "Post Author" }, "influencer_uid": { "type": "string", "description": "Influencer UID that is assigned to the post" }, "shared": { "type": "boolean", "description": "Indicates whether the post is a shared piece of content (e.g. retweet)" }, "shared_author": { "type": "string", "optional": true, "description": "The original author of the content being shared (if applicable)" }, "shared_url": { "type": "string", "optional": true, "description": "The original URL of the content being shared (if applicable)" }, "language": { "type": "string", "optional": true, "description": "The detected language ISO code of the post content" }, "metrics": { "type": "array", "optional": true, "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Metric name" }, "value": { "type": "number", "description": "Metric value" } } } }, "potential_reach": { "type": "string", "optional": true, "description": "Potential audience of the author (at time of publication)" } } } }, "aggregations": { "type": "object", "properties": { "<aggregation name 1>": { "type": "object", "description": "Name of the aggregated counts", "properties": { "buckets": { "type": "array", "optional": true, "description": "The aggregation buckets", "items": { "type": "object", "properties": { "key": { "type": "string or long", "optional": false, "description": "The key for the bucket, string by default, long if it's a date histogram bucket" }, "key_as_string": { "type": "string", "optional": true, "description": "For date histogram buckets, the key as a date string representation" }, "count": { "type": "long", "optional": false, "description": "The count of records that matched the bucket" } } } }, "value": { "type": "long", "optional": true, "description": "Value from aggregations that return single numbers" }, "count": { "type": "long", "optional": true, "description": "For stats aggregations, the count of records that contributed to the stats" }, "min": { "type": "double", "optional": true, "description": "For stats aggregations, the min value that contributed to the stats" }, "max": { "type": "double", "optional": true, "description": "For stats aggregations, the max value that contributed to the stats" }, "avg": { "type": "double", "optional": true, "description": "For stats aggregations, the average of the values that contributed to the stats" }, "sum": { "type": "double", "optional": true, "description": "For stats aggregations, the sum of the values that contributed to the stats" } } }, "<aggregation name 2>": { "type": "object", "description": "Next aggregation if applicable..." } } }, "influencers": { "type": "object", "optional": true, "properties": { "{{influencer-UID}}": { "type": "object", "description": "Influencer profile (see 'Influencer Show' Expect Responses for full property descriptions). The key for this JSON object is the influencer UID that corresponds to the object's property values", "properties": [ "uid", "name", "description", "primary_affiliation", "title", "is_brand", "location", "thumbnail_url", "avatar", "reach", "resonance", "audience" ] } } } } }

  • GET*Post Search/posts/search
    Searches for relevant posts against a particular set of keywords. Supports a variety of filters, aggregations, and sorts. In addition, the posts' assigned influencers can be included in the response by setting include_entities=true
    
    

    Parameter	Value	Type	Description
    keywords		string	Keyword(s) to search on, comma-separated. See general guidelines above for usage
    exclusion_keywords		string	Keyword(s) to exclude on, comma-separated. The keyword types defined above apply here as well
    tags		string	List of tag filters, comma-separated. Tags are ANDed together. Useful for filtering influencers to a targeted group of people. Use in conjunction with the /influencers/tag/add and /influencers/tag/remove endpoints to customize your influencer groups
    tags_exclusive		string	Tags to ignore during the search process, comma-separated. Useful for discovering influencers outside a particular 'tag' segment
    is_tag_prefix	truefalse	boolean	If true, the tag(s) will be utilized in a prefix search (e.g. searching 'foo' would return the union of posts whose influencers are associated to tags 'foo/bar', 'foo/inc', etc.)
    influencers		string	Influencer UID(s) to restrict the search to, comma-separated (up to 500). Useful for surfacing content for a non-tagged group of people
    influencers_exclusive		string	Influencer UID(s) to exclude from the search, comma-separated (up to 500). Useful for excluding content for specific influencers
    channels		string	Channel UID(s) to restrict the search to, comma-separated (up to 500)
    channels_exclusive		string	Channel UID(s) to exclude from the search, comma-separated (up to 500)
    posts_inclusive		string	Post UID(s) to restrict the search to, comma-separated (up to 500)
    posts_exclusive		string	Post UID(s) to exclude from the search, comma-separated (up to 500)
    since_when		string	Only results with a published date greater than this timestamp will be returned. Expected date input format: YYYY-MM-DD'T'hh:mm:ssZ (e.g. 2012-06-30T13:30:00-0400)
    max_when		string	Only results with a published date less than this timestamp will be returned. Expected date input format: YYYY-MM-DD'T'hh:mm:ssZ (e.g. 2012-06-30T13:30:00-0400)
    since_id		string	Only results published after than the specified post UID will be returned
    max_id		string	Only results published before than the specified post UID will be returned
    root_urls_inclusive		string	Filter to restrict the post search to only those posts belonging to the specified root urls, comma-separated. Sub-domains are not supported
    root_urls_exclusive		string	Filter to restrict the post search to only those posts NOT belonging to the specified root urls, comma-separated. Sub-domains are not supported
    lang	allardadeenelesfifriditjakonlnoplptrusvtrtl	enumerated	Filter to restrict posts to the specified language
    include_brand_content	truefalse	boolean	Flag whether to include brand content as part of the post search
    include_shared_content	truefalse	boolean	Flag whether to include shared content (e.g. retweets) as part of the post search
    has_engagement	truefalse	enumerated	Filter to restrict posts to those that do -or- do not have engagement
    publication_types_inclusive	STORYSTREAM	enumerated	Filter to restrict posts by specific publication type(s) (comma-separated). Useful in combination with `root_urls_inclusive` parameter; e.g. to narrow down results to Instagram Stories, set publication_type_inclusive=STORY and root_urls_inclusive=instagram
    publication_types_exclusive	STORYSTREAM	enumerated	Filter to restrict posts by specific publication type(s) (comma-separated). Useful in combination with `root_urls_inclusive` parameter; e.g. to narrow down results to Instagram content except for Stories, set publication_type_exclusive=STORY and root_urls_inclusive=instagram
    influencer_name		string	Filter to restrict posts authored by influencers with a specific name
    influencer_gender	allmalefemale	enumerated	Filter to restrict posts authored by influencers with a specific gender
    influencer_emails		string	Filter to restrict posts authored by influencers with a specific email. Allows up to 100 emails to be used at once, comma-separated
    influencer_iso_location		string	Filter to restrict posts authored by influencers with a particular geo-location. Expected format is a JSON array of one-to-many geo-filter JSON objects. For example, if you wanted to find all influencers in the U.S. but not in Massachusetts, the geolocation JSON string would look like: "[ {"type":"INCLUSION", "fields":{"COUNTRY":"US"}}, {"type":"EXCLUSION", "fields":{"STATE":"US-MA"}}]". The supported fields within the "fields" object are [GEODIVISION, GEOSUBDIVISION, COUNTRY, STATE, COUNTY]. All values for [COUNTRY, STATE, COUNTY] should be ISO-3166 compliant (see http://en.wikipedia.org/wiki/ISO_3166-2). All values for [GEODIVISION, GEOSUBDIVISION] come from the UN M.49 standard (see http://en.wikipedia.org/wiki/UN_M.49) and should be prefixed with UN (e.g. for Americas, use value "UN019"
    influencer_title		string	Filter to restrict posts authored by influencers that contain specific words in their title, comma-separated.
    influencer_bio		string	Filter to restrict posts authored by influencers that contain specific words in their bio, comma-separated.
    influencer_affiliation		string	Filter to restrict posts authored by influencers that contain specific words in their affiliation, comma-separated.
    influencer_all_filter		string	Filter to restrict posts authored by influencers that contain specific words in either their name, title, bio, affiliation or text_location. Operates as a catch-all influencer filter
    influencer_is_verified	truefalse	enumerated	Filter to restrict posts authored by influencers with a specific Twitter verified status
    influencer_reach_min		double	Filter to restrict posts authored by influencers within a minimum reach threshold (inclusive). Expected value is of type Double where 0.01 <= val <= 1. Defaults to lower-bound
    influencer_reach_max		double	Filter to restrict posts authored by influencers within a maximum reach threshold (inclusive). Expected value is of type Double where 0.01 <= val <= 1. Defaults to upper-bound
    influencer_resonance_min		double	Filter to restrict posts authored by influencers within a minimum resonance threshold (inclusive). Expected value is of type Double where 0.01 <= val <= 1. Defaults to lower-bound
    influencer_resonance_max		double	Filter to restrict posts authored by influencers within a maximum resonance threshold (inclusive). Expected value is of type Double where 0.01 <= val <= 1. Defaults to upper-bound
    include_keyword_matches	truefalse	boolean	Flag whether to include matched keywords for each post result. Setting this flag to true has performance penalties, so use it wisely
    include_entities	truefalse	boolean	Flag whether to include influencer entities in the response
    aggregations		string	JSON string representing a set of enabled aggregations referenced by their name (accepted values - `agg_keyword`, `agg_influencers`, `agg_domains`, `agg_hashtags`, `agg_publication_types`, `agg_links`, `agg_monthly`, `agg_weekly`, `agg_daily`, `agg_metrics`, `agg_engagement`, `agg_engagement_rate`, `agg_comments`, `agg_estimated_impressions`, `agg_impressions`, `agg_reactions`, `agg_shares`, `agg_video_views`, `agg_story_views`, `agg_actualized_reach`, `agg_potential_reach`). An aggregation value can either be a boolean (true to enable) or a child JSON structure defining a sub-aggregation or additional params. E.g. {"agg_keyword":{"agg_influencers":true},"agg_domains":{"size":25},"agg_hashtags":{"size":0,"distinct_count":true}}. Top-level aggregations provide analytics over the original search result-set, while sub-aggregations provide analytics scoped to their parent `bucket`. All aggregations are `bucket` aggregations that return `n` buckets with aggregated counts, except for aggregations around engagement and metrics that return statistical values (sum, avg., etc.). The caller can use the `size` param to modify how many buckets are returned (which may impact performance) and also use `distinct_count` to produce a metric aggregation with estimated total `bucket` count (use `size:0` along with `distinct_count:true` for better performance if `bucket` count is only required). Certain params are not supported by all aggregations and may throw errors.
    aggregation_timezone		string	The time zone under which to compute any date related bucketing / aggregations. Please refer to http://joda-time.sourceforge.net/timezones.html for accepted offsets or canonical ids (e.g. both -05:00 and America/New_York are acceptable).
    sort	daterelevanceengagement_ratepotential_reachtotal_engagementstotal_commentstotal_estimated_impressionstotal_impressionstotal_reactionstotal_sharestotal_video_viewstotal_actualized_reach	enumerated	Indicates how post matches will be sorted. Accepted sort values are ["date", "relevance", "potential_reach", "engagement_rate", "total_engagements", "total_comments", "total_impressions", "total_reactions", "total_shares", "total_video_views", "total_actualized_reach"]. Defaults to "date" if no value is provided
    sort_order	ascdesc	enumerated	Indicates the sort order of the results applied against the 'sort' parameter. Accepted sort order values are ["asc", "desc"]. Defaults to "desc" if no value is provided
    count		integer	The number of results to return per page, up to a max of 100. Defaults to 25
    page		integer	The results page number. Defaults to 0. Max pageable results (page * count) for this call is set at 2500
    customer_key		string	Use when passing tag filters to limit results to the tag namespace for your account (passing tag filters without a customer key will return an API error). Multiple customer keys are supported via the comma-delimited syntax and are implictly OR'ed together. If you don't have a customer key, contact api-support@traackr.com to have one issued to you.
    report_id		string	If this parameter is specified, the lookup of influencers will occur in the active snapshot index associated with the report_id

    Expect Responses

    Format

    Schema

    json

    { "type": "object", "properties": { "page_info": { "type": "object", "properties": { "has_more": { "type": "boolean", "description": "Indicates whether there are more results based on pagination" }, "current_page": { "type": "integer", "description": "Indicates the current page number for the results" }, "next_page": { "type": "integer", "description": "Indicates the next page number for the results. A value of 0 indicates no next page" }, "page_count": { "type": "integer", "description": "The requested number of results per page" }, "results_count": { "type": "integer", "description": "The actual number of results on the page" }, "total_results_count": { "type": "integer", "description": "The total number of results matching the search, irrespective of pagination (capped at 50k)" } } }, "posts": { "type": "array", "description": "Post search results", "items": { "type": "object", "properties": { "uid": { "type": "string", "description": "Post UID" }, "url": { "type": "string", "description": "Post URL" }, "root_domain": { "type": "string", "description": "Post Root Domain" }, "title": { "type": "string", "description": "Post Title" }, "truncated": { "type": "string", "optional": true, "description": "Indicates whether the post title is truncated (max of 200 chars)" }, "published_date": { "type": "string", "description": "Post Published Date" }, "author": { "type": "string", "description": "Post Author" }, "influencer_uid": { "type": "string", "description": "Influencer UID that is assigned to the post" }, "shared": { "type": "boolean", "description": "Indicates whether the post is a shared piece of content (e.g. retweet)" }, "shared_author": { "type": "string", "optional": true, "description": "The original author of the content being shared (if applicable)" }, "shared_url": { "type": "string", "optional": true, "description": "The original URL of the content being shared (if applicable)" }, "language": { "type": "string", "optional": true, "description": "The detected language ISO code of the post content" }, "keyword_matches": { "type": "array", "optional": true, "description": "The matched keywords for this particular post" }, "metrics": { "type": "array", "optional": true, "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Metric name" }, "value": { "type": "number", "description": "Metric value" } } } }, "potential_reach": { "type": "string", "optional": true, "description": "Potential audience of the author (at time of publication)" } } } }, "aggregations": { "type": "object", "properties": { "<aggregation name 1>": { "type": "object", "description": "Name of the aggregated counts", "properties": { "buckets": { "type": "array", "optional": true, "description": "The aggregation buckets", "items": { "type": "object", "properties": { "key": { "type": "string or long", "optional": false, "description": "The key for the bucket, string by default, long if it's a date histogram bucket" }, "key_as_string": { "type": "string", "optional": true, "description": "For date histogram buckets, the key as a date string representation" }, "count": { "type": "long", "optional": false, "description": "The count of records that matched the bucket" } } } }, "value": { "type": "long", "optional": true, "description": "Value from aggregations that return single numbers" }, "count": { "type": "long", "optional": true, "description": "For stats aggregations, the count of records that contributed to the stats" }, "min": { "type": "double", "optional": true, "description": "For stats aggregations, the min value that contributed to the stats" }, "max": { "type": "double", "optional": true, "description": "For stats aggregations, the max value that contributed to the stats" }, "avg": { "type": "double", "optional": true, "description": "For stats aggregations, the average of the values that contributed to the stats" }, "sum": { "type": "double", "optional": true, "description": "For stats aggregations, the sum of the values that contributed to the stats" } } }, "<aggregation name 2>": { "type": "object", "description": "Next aggregation if applicable..." } } }, "influencers": { "type": "object", "optional": true, "properties": { "{{influencer-UID}}": { "type": "object", "description": "Influencer profile (see 'Influencer Show' Expect Responses for full property descriptions). The key for this JSON object is the influencer UID that corresponds to the object's property values", "properties": [ "uid", "name", "description", "primary_affiliation", "title", "is_brand", "location", "thumbnail_url", "avatar", "reach", "resonance", "audience" ] } } } } }

• Account Management

  • List Methods
  • Expand Methods

  • POSTCreate Customer Key/account_mgmt/customerkey/create
    Generates a new Customer Key hash.
    
    

    Parameter	Value	Type	Description
    customer_name		string	Human readable name for Customer Key. This customer name needs to be unique for your API key or an HTTP status code of 400 will be returned

    Expect Responses

    Format	Schema
    json	{ "type": "object", "properties": { "customer_key": { "type": "string", "description": "A new Customer Key" } } }

  • POSTEdit Customer Key/account_mgmt/customerkey/edit
    Edits a customer key in your account.
    
    

    Parameter	Value	Type	Description
    customer_key		string	The customer key associated with your account
    external		string	Whether this customer key is associated to an external account
    iso_location		string	Filter to restrict influencers to a particular geo-location. Expected format is a JSON array of one-to-many geo-filter JSON objects. For example, if you wanted to find all influencers in the U.S. but not in Massachusetts, the geolocation JSON string would look like: "[ {"type":"INCLUSION", "fields":{"COUNTRY":"US"}}, {"type":"EXCLUSION", "fields":{"STATE":"US-MA"}}]". The supported fields within the "fields" object are [GEODIVISION, GEOSUBDIVISION, COUNTRY, STATE, COUNTY]. All values for [COUNTRY, STATE, COUNTY] should be ISO-3166 compliant (see http://en.wikipedia.org/wiki/ISO_3166-2). All values for [GEODIVISION, GEOSUBDIVISION] come from the UN M.49 standard (see http://en.wikipedia.org/wiki/UN_M.49) and should be prefixed with UN (e.g. for Americas, use value "UN019"
    impression_deflators		string	Metric deflators used to calculate estimated impressions. Expected format is a JSON array of deflator objects with the following schema: {"platform": "INSTAGRAM", "in_feed_deflator": 0.5, "type_deflators": {"STORY": 0.95}}

    Expect Responses

    Format	Schema
    json	{ "type": "object", "properties": { "status": "ok" } }

  • GETView Customer Key/account_mgmt/customerkey/view
    Views a customer key in your account.
    
    

    Parameter	Value	Type	Description
    customer_key		string	The customer key associated with your account

    Expect Responses

    Format

    Schema

    json

    { "type": "object", "properties": { "customer_key": { "type": "string", "description": "The customer key" }, "customer_name": { "type": "string", "description": "The customer name that was used to create the customer key" }, "iso_location": { "type": "array", "description": "JSON array of one-to-many geo-filter JSON objects; can be missing if never defined, or an empty array if reset", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "INCLUSION, EXCLUSION" }, "fields": { "type": "object", "properties": { "GEODIVISION, GEOSUBDIVISION, COUNTRY, STATE, COUNTY": { "type": "string", "description": "ISO/UN code" } } } } } }, "impression_deflators": { "type": "array", "description": "JSON array of metric deflators used to calculate estimated impressions" } } }

  • DELETEDelete Customer Key/account_mgmt/customerkey/delete
    Deletes the customer key for your account. The caller must first manually untag all influencers associated with their account or include the force_untag=true flag with the request. Else, the deletion will fail with an HTTP status code of 400
    
    

    Parameter	Value	Type	Description
    customer_key		string	The customer key associated with your account
    force_untag	truefalse	boolean	Force untag all influencers associated with your account.

    Expect Responses

    Format	Schema
    json	{ "type": "object", "properties": { "status": "ok" } }

  • GETList Account Tags/account_mgmt/tag/list
    List the account tags associated with the customer key
    
    

    Parameter	Value	Type	Description
    customer_key		string	The customer key associated with your account
    tag_prefix_filter		string	Filters which tags are returned to include only those tags that start with the provided prefix value

    Expect Responses

    Format	Schema
    json	{ "type": "object", "properties": { "account": { "type": "object", "properties": { "tags": { "type": "array", "description": "Customer Account tags", "items": { "type": "object", "properties": { "tag": { "type": "string", "description": "Tag name" }, "ref_count": { "type": "int", "description": "Number of influencers containing this tag" } } } } } } } }