What is Neticle Data API?

Neticle’s Data API is a standard REST API for retrieving all the data that is available in our system.

It makes the integration of analyzed textual and aggregated data to any third-party system possible, directly or via connectors. The most frequent (but not exclusive) use cases are:

Channeling Neticle’s enhanced textual data (mentions) into your own BI system
Getting aggregations / KPIs for your own dashboards
Retrieving identified insights on keywords

Authorization of Data API

We standardized all different ways of authentication in this new iteration of the Data API, including (but not limited to) the ApiKey-based authentication method. We've made sure that your existing ApiKey is still valid. However, the way you need to provide it to the API has changed.

Going forward, no matter the form of credentials you possess, they will be communicated through the Authorization header. You can use [basic auth standard] to specify your ApiKey, which defines its basic shape as follows:

Authorization: Basic <credentials>

To generate the value for the header, you can take the following steps:

Take your existing ApiKey or request a new one.
Append a : (colon) character at the end.
Take the string you created in step 2, and apply a Base64 encoding over it. You should use a standard Base 64 encoder (for example .btoa() in JS), and not its url-compatible variant!
Take the result string from step 3 and prepend the string "Basic " at the start.
You can use the string from step 4 as the value of the Authorization header.

For the rest of this documentation, the closed lock icon will indicate endpoints which are protected, and where you must provide an Authorization header to be able to successfully receive a response from them.

Endpoints with the open lock icon can be used without any Authorization header.

In case you want to read more and edit examples of ApiKeys, visit the Data API documentation here.

Rate limiting

All of our endpoints are limited for querying in a given timeframe. We differentiate our rate limiting policy based on the authorization of the endpoints:

ApiKey protected endpoints
No more than 5000 requests can be processed in each 1 hour timeframe with the same ApiKey. (This means no more than 83 requests/min or 1.3 requests/sec in average for 1 hour.)
Endpoints without ApiKey authorization
No more than 60 requests can be processed in each 1 minute timeframe from the same IP address.

In each API response's response header we embed the current quota usage information:

RateLimit-Limit: <number> - max allowed queries in the timeframe
RateLimit-Remaining: <number> - how many queries can be made for the same endpoint and for all other endpoints with the same authorization method
RateLimit-Reset: <number> - seconds left until the end of the current timeframe, when the quota usage resets
RateLimit-ResetAt: <number> - timestamp when the time frame ends

In particular we suggest not to perform more than 1 query in each sec to our API, so no rate limitation error will be responded.

Versioning

Depreciation policy

When a new API version is released, the older ones start their 6 month depreciation period. We plan new versions twice a year, approximately 6 months apart. The different versions may or may not be backwards compatible.

Versioning scheme

Since September 2022, we no longer use the SemVer but the CalVer versioning scheme.

The minor changes will not increase the API version and should be backwards compatible so no URL modification is needed from your side.

Because of this approach, the response structure JSONs never miss a previously existing key, but the JSONs can be extended with new keys within the same version. New endpoints may also be added without increasing the version.

Connecting Data API with Microsoft Power BI

Microsoft Power BI is a powerful tool for data visualization and business intelligence. Integrating it with Neticle’s Data API allows you to seamlessly import and analyze your online data. This article provides a step-by-step guide to connect Neticle’s Data API with Power BI.

Prerequisites

Before you begin, ensure you have the following:

Data API Access: Make sure you have your API token.
Microsoft Power BI Desktop: Download and install Power BI Desktop if you haven’t already.

Step-by-step Guide

1. Obtain Your API Endpoint and Token

Ensure you have the endpoint URL and API token from your Data API documentation.

Log in to the Neticle Media Intelligence portal
Go to ‘integrations’ under personal settings
Choose Neticle Data API under the outbound integration types
Click “+Add”
The system generates a label for the new token (this can be re-written per need)
Click ‘create’
The access key can be copied to clipboard by clicking the blue icon on the right side of the access key

2. Open Power BI Desktop

Launch Power BI Desktop on your computer.

3. Get Data from Web

Click on 'Get Data’ from the Home tab.
Select 'Web' and click 'Connect'

4. Enter API URL

In the URL field, enter the API endpoint. You can choose from different endpoints regarding your needs:
- Retrieving mentions (usually for feed-like visualisation) - https://data.neticle.com/docs/24.04#mentions:listing-mentions
- Retrieving aggregated data in JSON format - https://data.neticle.com/docs/24.04#aggregations:kpis
- Retrieving aggregated data in Higcharts optimised JSON format - https://data.neticle.com/docs/24.04#chart-template-data:finding-chart-data-by-chart-template
  - This might need extra steps at first usage to identify the best chart template for your use case. All chart templates represent an available chart in Neticle Media Intelligence. The available chart templates can be retrieved here: https://data.neticle.com/docs/24.04#chart-templates:listing-chart-templates