What’s an API?

The acronym “API” stands for “Application Programming Interface”. An API is a defined way for a program to accomplish a task, usually by retrieving or modifying data. In Cognitive Insights’ case, we provide an API method for developers and companies to receive cognitive linguistic based data on their users. Programmers can use Cognitive Insights to make applications, websites, widgets, and other projects.

How do I use the Cognitive Insights console?

The Cognitive Insights console allows you to view and test calls to our REST API. By using Apigee’s GUI, you are able to specify calls to our API, and view the response. If you wish to start using our API as a part of your application, we recommend using the console in order to get acquainted with the functionality of the API.

How do I obtain authorization to use the application?

We use a username/password combination for authentication within our API. If you wish to obtain a proper username/password combination for use with your app, you must submit your proposed username/password as parameters to the createUser API call. If your username/password combination is unique, you will be authorized to access our API using that combination.

What protocol does the Cognitive Insights API use?

Cognitive Insights is a REST API.

What kind of data can I get from the API?

The API provides insight into personality traits of individuals given their online textual communications. Our API can provide you with personality insights, if it is given text to analyze according to our specifications. On top of analysis, our API offers storage of your data. For each unique author of text given, our API stores their predicted personality traits, as well as time-dependent personality predictions, i.e. predictions for text from a given day, month or year, too.

What kind of data does Cognitive Insights capture?

Cognitive Insights suite of APIs goes beyond existing analytic frameworks in the way it synthesizes personal information from online communications. It uses unique, cognitively-driven algorithms to retrieve not just semantic information from text, but also sentiment, personality and demographics information. Our suite of APIs gives you the ability to unlock a more complete understanding of a person and their interaction with the online world than other analytics services.

Do I have to authorize each API within Cognitive Insights separately?

No you do not – each username/password combination that a user creates gives them authorization to use all of our APIs. So, if you have only been using one of the APIs, and which to start using another, you will already be able to access authenticated requests to the new API using your username/password combination.

What data formats are supported by Cognitive Insights?

JSON is the supported format of the Cognitive Insights API suite. Some calls will also use HTM format.

How will I be aware of changes made to the Cognitive Insights API suite?

There are a few ways to follow the changes we make to our platform:

1. Follow us @BMediaNetworks.
2. Track our coding at GitHub.
3. Consult BMN’s Cognitive Insights web page.

 

Authentication

Does access to the Cognitive Insights API expire?

In this first version of the Cognitive Insights API, your access to the API will not expire. Your username/password combination will remain in effect unless you determine that you would like to remove yourself as a user of our API.

How do password resets effect application authorization?

Connectivity and permissions do not change when a user resets their password. The relationship between Cognitive Insights, a user, and a third-party application do not involve a username and password combination.

 

Application Management:

How do I allow additional users to maintain my application record?

You are allowed to give your username and password to other users if you so desire. Be careful with distributing this information, as it will give them access to all of the contents of your repository of information.

How do I transfer my application to another account?

Unfortunately we do not currently support this capability in the first version of our API. However, a user may have multiple accounts if they wish – you can use this as an alternative for now. In future versions of our API, this ability will be added in.

 

Troubleshooting:

Is my IP banned or blacklisted?

Being banned or blacklisted means the Cognitive Insights APIs will not respond to requests you make to them. You know if you have been blacklisted because the APIs will not respond to you at all. If this happens to you the first thing to do is stop any requests your application is making. Then see if you can reach other URLs using a command line tool like curl. The support team will also be contacted regarding any banned or blacklisted IPs.

Cognitive Insights provides APIs with no guarantees of service availability. This means we may take steps to ban or block any account, IP, or range of IPs that might be harming our ability to provide our services in a timely and reliable way.

The best way to avoid being blacklisted is to pay attention to the remaining API requests you are allowed to make, and to handle errors appropriately. Handling errors appropriately means reducing your request frequency (throttling) or stopping requests until you can identify why the request failed.

If you have sufficiently diagnosed your network connectivity and believe your IP may have been blacklisted, please post on Stack Overflow using one of the following tags: #cognitive-insights, #personality-api, #bmedianetworks, #cognitive-insights-api. Provide as much detail as possible about which steps you have taken.

Is the Cognitive Insights API down? Where can I find information about platform health?

You can follow @BMediaNetworks> and BMN on Facebook or consult the BMN News page for updates about service health, new features, and more.

What am I doing wrong?

Troubleshooting with the API is usually done with these steps:

• Examine the HTTP response closely: the status code you received back, the message that accompanies that code, the HTTP headers in the response, and the response body itself — the response body usually contains the most specific information about the nature of an error.
• If the response body doesn’t help identify the problem, check @BMediaNetworks, Stack Overflow, or Cognitive Insights’ home page to see if there are any known issues with the API at that time.
• If you are using your own library, try using another library or curl to see if the same issue occurs.
• If you are still seeing problems send a message to BMN so that our programmers and engineers can try and help you. Make sure you include the request that is failing and the response (including headers) that you get back. The more information you provide in the email the quicker somebody can help you out.

Please avoid creating bug reports until the developer mailing list has tried to help you first.

Getting help:

How do I deactivate an account?

Deactivating accounts cannot be accomplished with the API. Please contact BMN to pursue this issue.

How do I get my account verified?

This site is focused on programmatic uses of the Cognitive Insights platform. We do not review nor approve any requests for the closed account verification program. Please do not use this site to request verification. If you have any questions about verification, you can post on Stack Overflow using one of the following tags: #cognitive-insights, #personality-api, #bmedianetworks, #cognitive-insights-api, or send a message to BMN.

How do I report bugs and request features?

Before filing an issue to report a bug or request a feature, please:

1. Search Stack Overflow for similar issues and requests. If you find an active topic about the issue, use that thread to continue discussing it.
2. Check BMN’s API site for any reported problems.
3. If you cannot find your issue in the Stack Overflow discussions or on the BMN site, consider starting a discussion topic. By creating a discussion topic, BMN employees and third party developers can discuss the problems you are having and rule out any already-known issues, common developer error, issues with the service, or other instant resolutions to your potential issue.
4. If you’re absolutely sure that what you are filing is a material issue with the platform, file an issue with as exhaustive detail as possible to reproduce your problem. Insufficiently described issues will be closed in favor of the reporter opening a discussion to further refine the issue description. Make sure to include the exact URLs you’re executing, the exact POST bodies and headers you are sending and any other relevant details. When reporting an issue, include a signature base string as well. Refrain from ever submitting your consumer secret.

I want to partner with Behavioral Media Networks; how do I reach the business development team?

Behavioral Media Networks is always looking for new opportunities to meet people and form new partnerships. If you are interested in partnering with BMN, contact us directly on our website and we will do our best to get back to you shortly.

What do I do if my account is compromised, hacked, or used outside of my control?

If you’re having any questions about the security of your account, please contact BMN directly.

REST API:

What output formats does the Cognitive Insight API support?

We support JSON only.

Will the API require authentication?

Yes, this API requires authentication on all authorized call. Authentication is done via Basic Authentication, over SSL-encrypted requests (HTTPS requests).