Get mentions from the project

This method takes filter parameters as URL query parameters and returns mentions matching those filters.

GET https://api.smelter.ai/v1/mentions/<account_name>/<project_name> — get mentions from the project.

Example:

https://api.smelter.ai/v1/mentions/myaccount/myproject?docs_per_page=100&newest_post_timestamp=1674147188
&&oldest_post_timestamp=1673253298countries=pt&countries=br

The response for this request returns maximum 100 mentions, including mention date in interval from 167325329 to 1674147188, only for Portugal and Brazil.

Filtering parameters

The available parameters are listed below:

only_main_topic=true — returns only relevant mentions. If the parameter value is false returns raw mentions as well.

countries=pt,br — a list of countries.

languages=por,esp — a list of languages.

newest_post_timestamp=1674147188&oldest_post_timestamp=1673253298 — time restrictions in the UNIX timestamp format. post_timestamp is a moment, when the mention appeared on the internet according to our data.

newest_insert_timestamp=1674147188&oldest_insert_timestamp=1673253298 — time restrictions in the UNIX timestamp format. insert_timestamp is a moment, when we processed the addition of the mention to your project.

source_names=twitter.com,facebook.com — returns mentions only from those sourses. Use second level domain names without http/https.

sentiment=positive,negative — restricts mentions by sentiment. Available sentiment types: positive, negative and neutral. Irrelevant mentions can't be analysed by sentiment.

search_query=complaint — mentions containing the word "complaint" in their snippet.

tags=mytag1,mytag2 — mentions containing tags.

Minus-filters

You can add minus-filters to all filtering parameters except sentiment.

For example:

source_names=-twitter.com,-facebook.com — returns mentions for all sources except twitter.com and facebook.com.

Display parameters

page_size=100 — restricts the maximum amount of returned mentions to 100 per page.

sort_by=newest_post_timestamp — a sorting order: from the newest to the oldest (by default). Available options: newest_post_timestamp, oldest_post_timestamp, newest_insert_timestamp, oldest_insert_timestamp.

Response format

The method returns mentions in the following format:

{
"data": [
    {
       "title": "Post title",
       "url": "https://subdomain.source_name.com/url",
       "source_name": "source_name.com",
       "post_timestamp": 1682521449,
       "insert_timestamp": 1682521459,
       "snippet": "Some snippet",
       "is_main_topic": true,  # can be false
       "language": "eng",
       "country": "br",
       "sentiment": "positive",
       "tags": ["mytag1", "mytag2"],
       "mention_id": "cddeb635593ed4ee00",
    },
    {
    ...
    }
],
"next_page_url": "https://api.smelter.ai/v1/mentions/myaccount/myproject?..." # url to retrieve next page if available,
"has_next_page": true
}

Pagination

You can split the response into several pages, if there are enough available mentions.

The parameter has_next_page in a response will be active.

Also you can use the parameter next_page_url — it can be used for retrieving the next page.

Response codes

Good response

The good response has the following format:

{
"data": useful_data,
"has_next_page": true # for paginated responses,
"next_page": "url" # next page if available for paginated responses

other fields
}

Bad response

The bad responses are code 400 and similiar HTTP codes.

{
"error": {
"code": "ChannelNotFound",
"message": "Project does not exist"
}
}

Errors

The possible errors are listed below:

— ChannelNotFound

— AccountNotFound

— MentionNotFound

— ValidationError — JSON has incorrect fields.

— TagNotFound — the tag from the filter is not found.