Table of Contents

URL

https://api.brandmentions.com/command.php?api_key=API_KEY

Error Codes

  1. Missing command
  2. Invalid command
  3. Missing API key
  4. Invalid API key
  5. Limits reached
  6. Unknown error
  7. Search not ready
  8. Unexpected error
  9. Invalid search hash
  10. Missing keywords
  11. Empty keywords
  12. Invalid time range
  13. Invalid language
  14. Invalid country
  15. Failed adding project
  16. User not found
  17. Reached total projects limit
  18. Missing project ID
  19. Invalid project ID
  20. Missing page
  21. Invalid page
  22. Invalid active sources
  23. Too many keywords
  24. Too short keyword
  25. Duplicate keywords
  26. Too long keyword
  27. Too many required keywods
  28. Too short required keyword
  29. Too long required keyword
  30. Too many excluded keywords
  31. Too short excluded keyword
  32. Too long excluded keyword
  33. Too many excluded domains
  34. Too short excluded domain
  35. Too long excluded domain
  36. Invalid sources
  37. Invalid quality filter
  38. Invalid linked value
  39. Invalid start period
  40. Invalid end period
  41. Invalid period
  42. Too small keyword index
  43. Too big keyword index
  44. Invalid callback URL
  45. Missing mentions per page
  46. Invalid mentions per page
  47. Project delete error
  48. Project delete failed
  49. Invalid stop web at
  50. Invalid stop social at
  51. Invalid email
  52. Invalid alert frequency
  53. Alert frequency value as_it_happens not allowed. Please contact support@brandmentions.com to activate it
  54. Missing user ID
  55. Unknown user ID
  56. Abusive behavior detected
  57. Missing email
  58. Missing period
  59. Reached total keywords limit
  60. Historical data already run for selected period
  61. 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
email 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"}