Table of Contents
- URL
- Error Codes
- PostSearch
- GetMentions
- GetProcessedMentions
- GetRemainingCredits
- AddProject
- ListProjects
- DeleteProject
- GetProjectMentions
- GetProjectInfluencers
- RunProjectHistorical
URL
https://api.brandmentions.com/command.php?api_key=API_KEY
Error Codes
- Missing command
- Invalid command
- Missing API key
- Invalid API key
- Limits reached
- Unknown error
- Search not ready
- Unexpected error
- Invalid search hash
- Missing keywords
- Empty keywords
- Invalid time range
- Invalid language
- Invalid country
- Failed adding project
- User not found
- Reached total projects limit
- Missing project ID
- Invalid project ID
- Missing page
- Invalid page
- Invalid active sources
- Too many keywords
- Too short keyword
- Duplicate keywords
- Too long keyword
- Too many required keywods
- Too short required keyword
- Too long required keyword
- Too many excluded keywords
- Too short excluded keyword
- Too long excluded keyword
- Too many excluded domains
- Too short excluded domain
- Too long excluded domain
- Invalid sources
- Invalid quality filter
- Invalid linked value
- Invalid start period
- Invalid end period
- Invalid period
- Too small keyword index
- Too big keyword index
- Invalid callback URL
- Missing mentions per page
- Invalid mentions per page
- Project delete error
- Project delete failed
- Invalid stop web at
- Invalid stop social at
- Invalid email
- Invalid alert frequency
- Alert frequency value
as_it_happens
not allowed. Please contact support@brandmentions.com to activate it - Missing user ID
- Unknown user ID
- Abusive behavior detected
- Missing email
- Missing period
- Reached total keywords limit
- Historical data already run for selected period
- Invalid keyword match type
PostSearch
Definition
The PostSearch command allows you to create a search job that is executed on the spot. The processing is done asynchronously, which means that the command returns a search hash, which can be used to query for the results. The search hash can be used for GetMentions or GetProcessedMentions calls for an hour after the job is created.
Cost
1 PostSearch credit
Parameters
keyword1 ... keyword5 | mandatory a total of 5 keywords are allowed, each one 3 to 50 characters long |
match_type1 ... match_type5 | optional the match type values are: exact, broad and case_sensitive. by default exact match type is used |
time_range | optional the period when the mentions were published. accepted values are: hour, day, week, month. by default is day |
languages[] | optional array of two characters code of the languages the mentions must be in. by default any language is allowed |
countries[] | optional array of two characters code of the countries the mentions must be from. by default any country is allowed |
stop_web_at | optional the number of found web mentions after which the search is stopped. by default this limitation is ignored and the search stops after all mentions are found. if this is not set, the default limit for your account is used |
stop_social_at | optional the number of found social mentions after which the search is stopped. by default this limitation is ignored and the search stops after all mentions are found. if this is not set, the default limit for your account is used |
required_keywords1 ... required_keywords5 | optional each keyword has an optional list of required terms that must all be found in each valid mention |
excluded_keywords1 ... excluded_keywords5 | optional keyword has an optional list of excluded terms that must all not be found in each valid mention |
active_sources | optional only selected social sources, or web mentions will be kept after the project execution. the list of accepted values are: web, facebook, twitter, instagram, linkedin, pinterest, reddit, youtube . by default all the sources are used |
callback | optional the callback URL to be called when the search is done. the call will be a POST request with the unique search identifier set in the search_hash field |
Input URL example
https://api.brandmentions.com/command.php?api_key=API_KEY&command=PostSearch&keyword1=brandmentions&keyword2=brand+mentions&match_type1=broad&time_range=day&languages[]=en&countries[]=US&stop_web_at=50&stop_social_at=50&required_keywords1[]=brand&excluded_keywords2[]=seo&active_sources[]=web&active_sources[]=twitter&callback=https://brandmentions.com
Output example
{"status":"success","search_hash":3186302626}
GetMentions
Definition
The GetMentions command allows you to retrieve the complete result of search jobs executed on the spot. It is recommended to only call this endpoint after the PostSearch callback was issued. Previous calls will return the Search not ready message. Using an invalid search_hash will return the Invalid search hash message.
Cost
0 credits
Parameters
search_hash | mandatory the identifier returned by the PostSearch command |
Input URL example
https://api.brandmentions.com/command.php?api_key=API_KEY&command=GetMentions&search_hash=3186302626
Output example
{"status":"success","mentions":[{"date":"2019\/04\/14 10:54","type":"web","title":"SGZ - Share Talk/","url":"https:\/\/www.share-talk.com\/tag\/sgz\/","performance":11,"social":{"facebook":0,"google_plus":0,"linkedin":0,"pinterest":0},"text":{"before":"...Tag: SGZ Total 1 Posts Mining Weekly Mining Highlights Weekly Mining Highlights, Sunday 7th April 2019 abm April 7, 20","keyword":"1","after":"9 A look back at some of the top stories this week from London\u2019s mining juniors Tweet Pin Share +1 Search..."},"sentiment":"positive","found_keyword":"brandmentions"}],"number_of_mentions":{"web":13,"social":16},"keywords":"brandmentions","language":"any","country":"ALL","remaining_credits":99}
GetProcessedMentions
Definition
The GetProcessedMentions command allows you to retrieve the partial result of search jobs executed on the spot. The recommended polling interval is 13 seconds. The polling must end once the processing_ended field has the value true. Using an invalid search_hash will return the Invalid search hash message.
Cost
0 credits
Parameters
search_hash | mandatory the identifier returned by the PostSearch command |
Input URL example
https://api.brandmentions.com/command.php?api_key=API_KEY&command=GetProcessedMentions&search_hash=3186302626
Output example
{"status":"success","mentions":[{"date":"2019\/04\/14 10:54","type":"web","title":"SGZ - Share Talk","url":"https:\/\/www.share-talk.com\/tag\/sgz\/","performance":11,"social":{"facebook":0,"google_plus":0,"linkedin":0,"pinterest":0},"text":{"before":"...Tag: SGZ Total 1 Posts Mining Weekly Mining Highlights Weekly Mining Highlights, Sunday 7th April 2019 abm April 7, 20","keyword":"1","after":"9 A look back at some of the top stories this week from London\u2019s mining juniors Tweet Pin Share +1 Search..."},"sentiment":"positive","found_keyword":"brandmentions"}],"number_of_mentions":{"web":13"social":16},"processing_ended":false,"keywords":"brandmentions","language":"any","country":"ALL","remaining_credits":99}
GetRemainingCredits
Definition
The GetRemainingCredits command allows you to get the number of credits left in the account. The PostSearch field in the result is the number of searches left in the current billing period. The AddProject field is the number of project left to create. The Mentions field is the total number of historical mentions left to store.
Cost
0 credits
Parameters
none
Input URL example
https://api.brandmentions.com/command.php?api_key=API_KEY&command=GetRemainingCredits
Output example
{"PostSearch":99,"AddProject":2,"Mentions":3459}
AddProject
Definition
The AddProject command allows you to create a new project that is saved in the user account and processed daily (or weekly, if set in the project settings).
Cost
1 AddProject credit
Parameters
keyword1 ... keyword5 | mandatory a total of 5 keywords are allowed, each one 3 to 50 characters long |
match_type1 ... match_type5 | optional the match type values are: exact, broad and case_sensitive. by default exact match type is used |
languages[] | optional array of two characters code of the languages the mentions must be in. by default any language is allowed |
countries[] | optional array of two characters code of the countries the mentions must be from. by default any country is allowed |
required_keywords1 ... required_keywords5 | optional each keyword has an optional list of required terms that must all be found in each valid mention |
excluded_keywords1 ... excluded_keywords5 | optional keyword has an optional list of excluded terms that must all not be found in each valid mention |
callback | optional the callback URL to be called when the search is done. the call will be a POST request with the unique search identifier set in the search_hash field |
websites | optional the websites that are going to be used to decide whether a mentions is linked or not |
excluded_domains | optional the subdomains or domains whose mentions that are going to be excluded, even if the project execution shows them valid |
active_sources | optional only selected social sources, or web mentions will be kept after the project execution. the list of accepted values are: web, facebook, twitter, instagram, linkedin, pinterest, reddit, youtube . by default all the sources are used |
quality_filter | optional all mentions are kept by default. only when this parameter has a non-empty value (like 1 or true), a curation of the mentions is done |
optional the email address where notifications will be sent when new mentions are found. by default the email address of the account holder is used | |
alert_frequency | optional the frequency by which the email notifications are sent. accepted values are: as_it_happens, day, week, month . the default value is day |
Input URL example
https://api.brandmentions.com/command.php?api_key=API_KEY&command=AddProject&keyword1=brandmentions&keyword2=brand+mentions&match_type1=broad&languages[]=en&countries[]=US&required_keywords1[]=brand&excluded_keywords2=seo&websites[]=brandmentions.com&excluded_domains[]=google.com&active_sources[]=web&active_sources[]=twitter&quality_filter=0&callback=https://brandmentions.com&email=email@example.com&alert_frequency=day
Output example
{"status":"success","project_id":"1"}
ListProjects
Definition
The ListProjects command allows you to get the list of projects in the user's account
Cost
0 credits
Parameters
none
Input URL example
https://api.brandmentions.com/command.php?api_key=API_KEY&command=ListProjects
Output example
{"status":"success","projects":[{"project_id":"1","name":"BrandMentions","keywords":[{"value":"brandmentions","expression":"phrase_match"}],"language":["any"],"country":["ALL"]}]}
DeleteProject
Definition
The DeleteProject command allows you to delete a project
Cost
0 credits
Parameters
project_id | mandatory the project ID |
Input URL example
https://api.brandmentions.com/command.php?api_key=API_KEY&command=DeleteProject&project_id=1
Output example
{"status":"success"}
GetProjectMentions
Definition
The GetProjectMentions command allows you to retrieve all saved mentions of a project in a paginated manner. optionally the most important filters are available
Cost
0 credits
Parameters
project_id | mandatory the ID of the project whose mentions are retrieved |
page | optional the page of mentions retrieved. default is 1 |
per_page | optional the number of mentions retrieved on one page. maximum is 100, which is also the default |
start_period | optional the beginning of the period for which the mentions are retrieved (it can be only the date, or date and time) |
end_period | optional the end of the period for which the mentions are retrieved (it can be only the date, or date and time) |
sources | optional either web, or the social networks for which the mentions are retrieved |
linked | optional either retrieve linked or unlinked mentions |
countries | optional the countries for which the mentions are retrieved. accepted values are: ALL, US, GB, AF, AL, DZ, AS, AD, AO, AI, AG, AR, AM, AU, AT, AZ, BS, BH, BD, BY, BE, BZ, BJ, BT, BO, BA, BW, BR, VG, BN, BG, BF, BI, KH, CM, CA, CV, CF, TD, CL, CN, CO, CD, CK, CR, HR, CU, CY, CZ, CI, DK, DJ, DM, DO, TL, EC, EG, SV, EE, ET, FJ, FI, FR, GA, GM, GE, DE, GH, GI, GR, GL, GP, GT, GG, GN, GY, HT, HN, HK, HU, IS, IN, ID, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KR, KW, KG, LA, LV, LB, LS, LY, LI, LT, LU, MK, MG, MW, MY, MV, ML, MT, MU, MX, FM, MD, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NZ, NI, NE, NG, NU, NF, NO, OM, PK, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RO, RU, RW, SH, WS, SM, ST, SA, SN, RS, SC, SL, SG, SK, SI, SB, SO, ZA, ES, LK, VC, SD, SR, SE, CH, TW, TJ, TZ, TH, TG, TK, TO, TT, TN, TR, TM, AE, UG, UA, UY, UZ, VU, VE, VN, VI, ZM, ZW |
Input URL example
https://api.brandmentions.com/command.php?api_key=API_KEY&command=GetProjectMentions&project_id=1&start_period=2019-03-15 15:37:22&end_period=2019-04-15 16:43:17&sources[]=web&linked=0&countries[]=ALL
Output example
{"status":"success","mentions":[{"published":"2021-01-28 11:08:00","url":"https:\/\/brandmentions.com\/blog\/twitter-historical-data\/","title":"Twitter Historical Data - The Fastest Way to Search & Get Historical Old Tweets","image_url":"https:\/\/brandmentions.com\/blog\/wp-content\/uploads\/2021\/01\/twitter-historical-data.jpg","performance":"70","language":"en","country":"US","tracked_keyword":"brandmentions","domain_influence":58,"social_network":null,"text":"Twitter historical data includes all the tweets and retweets that have ever been published, together with valuable insights about them. While Twitter offers","sentiment":"positive"}]}
GetProjectInfluencers
Definition
The GetProjectInfluencers command allows you to retrieve all influencers of a project in a paginated manner. optionally the most important filters are available
Cost
0 credits
Parameters
project_id | mandatory the ID of the project whose influencers are retrieved |
page | optional the page of mentions retrieved. default is 1 |
per_page | optional the number of mentions retrieved on one page. maximum is 100, which is also the default |
start_period | optional the beginning of the period for which the influencers are retrieved (it can be only the date, or date and time) |
end_period | optional the end of the period for which the influencers are retrieved (it can be only the date, or date and time) |
sources | optional the social networks for which the influencers are retrieved |
Input URL example
https://api.brandmentions.com/command.php?api_key=API_KEY&command=GetProjectInfluencers&project_id=1&start_period=2019-03-15 15:37:22&end_period=2019-04-15 16:43:17&sources[]=twitter
Output example
{"status":"success","influencers":[{"social_network":"twitter","username":"brandmentions","name":"BrandMentions","profile_pic":"https:\/\/pbs.twimg.com\/profile_images\/925664735655276544\/w4i3HaLM_normal.jpg","reach":1521,"followers":1521,"following":88,"mentions_count":82,"latest_mention":"2021-03-25 17:40:00"}]}
RunProjectHistorical
Definition
The RunProjectHistorical command allows you to run historical data retrieval for a project.
Cost
0 credits
Parameters
project_id | mandatory the ID of the project the ID of the project for which you retrieve the historical data |
period | mandatory the number of months of historical data to retrieve |
Input URL example
https://api.brandmentions.com/command.php?api_key=API_KEY&command=RunProjectHistorical&project_id=1&period=3
Output example
{"status":"success"}