Neticle Data API Quickstart Guide

Learn more about Neticle's Data Api

There are 2 ways to query mentions from the API, both serve different purposes:

1. Listing mentions fulfilling certain filters
2. Synchronizing mentions between systems

Finding your data sources

Both solutions require you to know what data source(s) you want to query (primarily: keywords).
You can list your available keywords by calling their listing endpoint. You can also use aspects
as data sources, and use their listing endpoint to query them. You can also list them in a single
request (along with other useful objects like the profiles and clients they belong to) by calling the
resources endpoint. Please note, that only resources your API key has access to will be listed
for you.

Listing mentions fulfilling certain filters

If you need results from multiple data sources at once, and may want to apply certain filters to
them, you can use the mentions endpoint of the Data API. This endpoint is good for displaying
feed-like interfaces, but was not designed for data synchronization.

If you need to display these mentions, or need additional information (for example the
user-displayable labels of a mention rather than just their IDs), this endpoint can make your life
easier if you set the “presentation.showRelatedResources” property to “true” or “1”. In this case,
you will receive additional information in the response’s “meta.relatedResources” property,
including the different kinds of labels, cities, regions, sources (content types), languages, own
channels, genders, aspects, and keywords present on the current page of mentions, as a
lookup map from their ids to their objects.

Synchronizing mentions between systems

When you want to load all your results from a single data source, you can use the data feed
endpoint of the Data API. Use this if you want to pull all your existing data from Neticle, and then
to poll for changes if you want to stay up-to-date.

Notes
Interval filter values

Interval filters expect their values as numeric timestamps, in UTC (you need to take care of the
time conversion, e.g.: if you want to query German data, you need to take the timezone and the
daylight saving rules when creating the filters which are currently GMT+2). They can handle
both seconds or milliseconds since the epoch. Please note, that both the “start” and the “end”
properties are inclusive, so if you want to query a whole day, you should construct them like so:

Query string serialization

Both endpoints expect their parameters in their URLs as query strings, the format of which
follows the de-facto URL parameter convention for describing nested objects.
Take the following JSON structure as an example:

{
"string": "value & more!",
"filters": {
"keywords": [1, 2],
"interval": {
"start": 1760313600000,
"end": 1760399999999
}
}
}

Serialized as a valid query string, it looks like the following (split into separate lines for clarity):

string=value%20%26%20more!&
filters[keywords][0]=1&
filters[keywords][1]=2&
filters[interval][start]=1760313600000&
filters[interval][end]=1760399999999

Please note, that only the individual keys/values need to be URL encoded, not the whole string.
The special characters "=", "[", "]" and "&" are important to be able to properly parse the
structure. Additionally, skipping an URL encoding on a string value (the value of the “string” field
in the above example) can also lead to an invalid query string.

The following example is invalid, because it does not apply URL encoding on the string “value &
more!”:

string=value & more!&
filters[keywords][0]=1&
filters[keywords][1]=2&
filters[interval][start]=1760313600000&
filters[interval][end]=1760399999999

The following example is also invalid, because it applies the URL encoding on the whole query
string:

string%3Dvalue%20%26%20more!%26
filters%5Bkeywords%5D%5B0%5D%3D1%26
filters%5Bkeywords%5D%5B1%5D%3D2%26
filters%5Binterval%5D%5Bstart%5D%3D1760313600000%26
filters%5Binterval%5D%5Bend%5D%3D1760399999999