Neticle Media Intelligence Skill

This skill provides complete integration with the Neticle Data API — a social media monitoring and data analytics platform. It enables querying mentions, aggregated KPIs, chart data, insights, and managing data collection configurations.

When to Use This Skill

Use this skill when the user:

• Needs to query social media mentions or sentiment data from Neticle
• Wants to get aggregated KPIs (volume, polarity, reach) for keywords or aspects
• Needs to synchronize mention data between Neticle and another system
• Wants to retrieve chart data or insights from Neticle
• Needs to manage Neticle keywords, aspects, own channels, or filters
• Mentions “Neticle”, “media intelligence”, “social listening”, or “mention monitoring”
• Wants to analyze brand sentiment, social media performance, or online reputation

Prerequisites

• API Key: The user must have a Neticle API key. Set it as:

  export NETICLE_API_KEY="<your-api-key>"
  

• curl and jq must be installed (standard on most systems)

API Overview

Rate Limit Headers

Every response includes these headers:

• RateLimit-Limit — max allowed queries in the timeframe
• RateLimit-Remaining — remaining quota
• RateLimit-Reset — seconds until quota resets
• RateLimit-ResetAt — timestamp when quota resets

Resource Hierarchy

Understanding Neticle’s hierarchy is essential:

Client
└── Profile
    ├── Keyword Group
    │   └── Keyword (data source)
    │       ├── Excludes
    │       ├── Synonyms
    │       ├── Own Channels
    │       └── Keyword Filters
    └── Aspect Group (data source)
        ├── Excludes
        └── Synonyms

Data sources are Keywords and Aspects (composite of Keyword + Aspect Group). You must specify at least one to query mentions, aggregations, or charts.

Using the API Script

This skill includes a bash script at scripts/neticle-api.sh that wraps all API endpoints.

Quick Start

# Set your API key
export NETICLE_API_KEY="your-api-key-here"

# Source the script to use functions directly
source scripts/neticle-api.sh

# Test connection
neticle_test_connection

# List all available resources
neticle_list_resources

# List mentions for a keyword
neticle_list_mentions '{"filters":{"keywords":[10001],"aspects":[]}}'

# Get KPIs
neticle_get_kpis '{"filters":{"keywords":[10001],"aspects":[]}}'

Or run as a CLI

bash scripts/neticle-api.sh test_connection
bash scripts/neticle-api.sh list_resources
bash scripts/neticle-api.sh list_mentions '{"filters":{"keywords":[10001],"aspects":[]}}'

Complete Endpoint Reference

1. Resource Discovery

Always start here to discover available data source IDs for subsequent queries.

2. Mentions (Core Data)

ViewFilter Structure (used by Mentions, Aggregations, Charts, Insights)

{
  "aspects": ["10001_20002"],       // required: string[] (keywordId_aspectGroupId)
  "keywords": [10001, 10002],       // required: number[]
  "interval": {                     // optional
    "start": 1760313600000,         // UTC timestamp (ms or s)
    "end": 1760399999999
  },
  "sources": [1],                   // optional: SourceGroup IDs
  "genders": [1],                   // optional: GenderGroup IDs
  "polarities": [1],                // optional: PolarityGroup IDs
  "filterLanguages": [],            // optional: language IDs
  "excludeLanguages": [],
  "filterCities": [],
  "filterRegions": [],
  "filterOwnChannels": [],
  "filterTags": [],
  "filterPhrases": {"values":[],"matchingType":"contains"},
  "excludePhrases": {"values":[],"matchingType":"contains"}
}

Mention Presentation (pagination & sorting)

{
  "currentPage": 1,
  "numberOfValues": 100,
  "includeResourceMap": false,
  "order": [{"by": 1, "direction": "desc"}]
}

Set includeResourceMap: true (or showRelatedResources: true) to get human-readable labels for source types, languages, cities, etc. in meta.relatedResources.

3. Data Feed (Bulk Synchronization)

Sync workflow:

1. Call /changes with dataSourceId (keyword or aspect ID), optionally with lastMentionId
2. If meta.nextPageToken is non-empty, call /next-page with that token
3. Repeat until nextPageToken is empty
4. Store the last mention’s ID for incremental polling

Parameters for /changes:

• dataSourceId (required): keyword ID (number) or aspect ID (string)
• lastMentionId (optional): resume from this point
• fromTimestamp (optional): only mentions created after this UTC timestamp
• withRelatedResources (optional): include resource labels

4. Aggregations

Both endpoints use the same ViewFilter structure (see above).

5. Charts

6. Insights

7. Keyword Management

8. Aspect Management

9. Data Collection Configuration

10. Suggestions

11. Reference Data

12. Deleted Mention Logs

Query String Serialization

GET endpoints expect nested objects as URL query strings:

{"filters":{"keywords":[1,2],"interval":{"start":1760313600000,"end":1760399999999}}}

Serializes to:

filters[keywords][0]=1&filters[keywords][1]=2&filters[interval][start]=1760313600000&filters[interval][end]=1760399999999

Rules:

• URL-encode individual values only (not the whole string)
• Bracket characters [ ] must remain unencoded
• & and = are structural separators

Response Format

All endpoints return an ApiPayload structure:

{
  "data": { ... },       // The response data
  "meta": {
    "totalCount": 100,
    "currentPage": 1,
    "nextPageToken": "...",
    "relatedResources": { ... }
  },
  "error": null          // Error details if request failed
}

Best Practices

1. Always start with /resources to discover available keyword and aspect IDs
2. Use Data Feed for bulk sync, Mentions endpoint for ad-hoc queries
3. Handle rate limits gracefully — check RateLimit-Remaining header
4. Data Feed polling — call at most once per minute per data source; 5-15 minutes recommended
5. Interval timestamps — both start and end are inclusive; use milliseconds for precision
6. Time zones — all timestamps are UTC; convert local times before querying
7. Pagination — default 100 items per page; Data Feed maxes at 1,000