Graphing Data

The idea for this endpoint is to be able to use it to graph keyword data, allowing you to build progression graphs. You'll use this endpoint to do analysis of keyword data over time. I.e. you can look at how many mentions of OpenAI there has been over the last 6 months, or negative mentions, broken down by month. You can also query to get back all keywords within the category Companies & Organizations, among others, to see which keywords have gone up or down during this period.

In general, this endpoint is usually interesting to do analysis rather than build tracking and news bots.

Graph Endpoint

This endpoint works by breaking apart the periods which allows you to look at the progression of a keyword, or keywords within a category. Depending on the period, we group the keyword statistics day by day, week by week, bi-weekly or monthly if you're looking at yearly data.

Properties

Name
period
Type
string (required)
Description
The period you are looking to get keyword data for. Periods available are daily, weekly, monthly, quarterly and yearly.
Name
slim
Type
bool (required)
Description
This property is by default set to true, if set to false it will show you exact sentiment numbers along with source ids. To get the links and texts from the sources, see » Sources Endpoint
Name
keywords
Type
string (required)
Description
Set the the keyword(s) for the data you want returned. You may set several keywords, seperated by a comma. You may set category instead of keyword.
Name
category
Type
string
Description
Set the category (within the 12 categories available) for the keyword data returned. Understand Categories » Q&A

GETpublic.api.safron.io/v2/graph

Public v2

This endpoint allows you to retrieve keyword data to graph broken down by a specifc period set.

Required attributes

Name
period
Type
string
Description
Set the period to daily, weekly or monthly. The quarter view looks at keyword data per 14 days, the monthly view looks at every 7 days, the weekly view every 3 days and then daily view for each day.
Name
slim
Type
bool
Description
This property is by default set to true, if set to false it will show you exact sentiment numbers along with source ids.
Name
keywords
Type
string
Description
Set the the keyword(s) for the data you want returned. You may set several keywords, seperated by a comma. You may set category instead of keyword.
Name
category
Type
string
Description
Set the category (within the 12 categories available) for the keyword data returned. Understand Categories » Q&A

Optional attributes

Name
limit
Type
integer
Description
Limit the amount of keywords returned, if category is set. The default is 10.
Name
type
Type
string
Description
Set the type of mentions counted by only post (post, article, newsletter and so on) or comment.
Name
search
Type
bool
Description
Search for a keyword rather find its exact match using the keyword parameter. You can use this one instead of keyword or category.
Name
source
Type
bool
Description
Set the specific source you want the data to orginate from. Some choices are hackernews, reddit, devto and github and so on.
Name
minMentions
Type
integer
Description
Only return results if a keyword has been mentioned a specified amount of times. Default is set at 10.
Name
authority
Type
integer
Description
Every mention is set with an engagement number, a keyword may be spammed if the keyword has a low authority score. Default is set at 1 but you may increase or decrease it.
Name
newSources
Type
bool
Description
Default is set to false. This property is not yet adaptable. It means that a new source will only be introduced in the statistics if it has existed during the entire period.

Request

GET

/v2/graph

curl -G https://public.api.safron.io/v2/graph \
  -d period=weekly \
  -d keywords=Elon%20Musk \
  -d slim=true

Response

{
    "period_chosen": "weekly",
    "keywords_found": 1,
    "slim_results": true,
    "results": 4,
    "keywords": [
        {
            "keyword": "Elon Musk",
            "date": "2024-08-12",
            "count": 45,
            "engagement": "high",
            "majority_sentiment": "neutral"
        },
        {
            "keyword": "Elon Musk",
            "date": "2024-08-03",
            "count": 26,
            "engagement": "medium",
            "majority_sentiment": "negative"
        },
        {
            "keyword": "Elon Musk",
            "date": "2024-08-09",
            "count": 64,
            "engagement": "high",
            "majority_sentiment": "neutral"
        },
        {
            "keyword": "Elon Musk",
            "date": "2024-08-06",
            "count": 116,
            "engagement": "high",
            "majority_sentiment": "negative"
        }
    ]
}

Rate limits apply to all public endpoints. See » Q&A.

GETprivate.api.safron.io/v2/keywords

Private v2

This private endpoint allows you to retrieve keyword data to graph broken down by a specifc period set. The private endpoints do not have usage limits and you may use quarterly and yearly data to graph.

Required attributes

Name
period
Type
string
Description
Set the period to daily, weekly, monthly, quarterly or yearly. The yearly view looks at data per month, the quarter view looks at keyword data per 14 days, the monthly view looks at every 7 days, the weekly view every 3 days and then daily view for each day.
Name
slim
Type
bool
Description
This property is by default set to true, if set to false it will show you exact sentiment numbers along with source ids.
Name
keywords
Type
string
Description
Set the the keyword(s) for the data you want returned. You may set several keywords, seperated by a comma. You may set category instead of keyword.
Name
category
Type
string
Description
Set the category (within the 12 categories available) for the keyword data returned. Understand Categories » Q&A

Optional attributes

Name
limit
Type
integer
Description
Limit the amount of keywords returned, if category is set. The default is 10.
Name
search
Type
bool
Description
Search for a keyword rather find its exact match using the keyword parameter. You can use this one instead of keyword or category.
Name
type
Type
string
Description
Set the type of mentions counted by only post (post, article, newsletter and so on) or comment.
Name
source
Type
bool
Description
Set the specific source you want the data to orginate from. Some choices are hackernews, reddit, devto and github and so on.
Name
minMentions
Type
integer
Description
Only return results if a keyword has been mentioned a specified amount of times. Default is set at 10.
Name
authority
Type
integer
Description
Every mention is set with an engagement number, a keyword may be spammed if the keyword has a low authority score. Default is set at 1 but you may increase or decrease it.
Name
newSources
Type
bool
Description
Default is set to false. This property is not yet adaptable. It means that a new source will only be introduced in the statistics if it has existed during the entire period.

Request

GET

/v2/graph

curl -G https://private.api.safron.io/v2/graph \
  -H x-api-key: {API_Key} \
  -d period=weekly \
  -d keywords=Elon%20Musk \
  -d slim=true

Response

{
    "period_chosen": "weekly",
    "keywords_found": 1,
    "slim_results": true,
    "results": 4,
    "keywords": [
        {
            "keyword": "Elon Musk",
            "date": "2024-08-12",
            "count": 45,
            "engagement": "high",
            "majority_sentiment": "neutral"
        },
        {
            "keyword": "Elon Musk",
            "date": "2024-08-03",
            "count": 26,
            "engagement": "medium",
            "majority_sentiment": "negative"
        },
        {
            "keyword": "Elon Musk",
            "date": "2024-08-09",
            "count": 64,
            "engagement": "high",
            "majority_sentiment": "neutral"
        },
        {
            "keyword": "Elon Musk",
            "date": "2024-08-06",
            "count": 116,
            "engagement": "high",
            "majority_sentiment": "negative"
        }
    ]
}

GETsafron.io/api/graph

Public v1 (Depreciated)

Depreciated endpoint for for graphing keyword data.

Required attributes

Name
period
Type
string
Description
Set the period to daily, weekly, monthly, quarterly or yearly. The yearly view looks at data per month, the quarter view looks at keyword data per 14 days, the monthly view looks at every 7 days, the weekly view every 3 days and then daily view for each day.
Name
keywords
Type
string
Description
Set the the keyword(s) for the data you want returned. You may set several keywords, seperated by a comma. You may set category instead of keyword.

Optional attributes

Name
type
Type
string
Description
Set the type of mentions counted by only post (post, article, newsletter and so on) or comment.
Name
source
Type
bool
Description
Set the specific source you want the data to orginate from. Some choices are hackernews, reddit, devto and github and so on.

Request

GET

/api/graph

curl https://safron.io/api/graph \
  -d period=weekly \
  -d keywords=Elon%20Musk

Response

[
  {
      "keyword": "Elon Musk",
      "date": "2024-08-12T00:00:00.000Z",
      "count": 45,
      "category": "People",
      "row_ids": [
          "wec-1723455713022",
          // ...
      ],
      "sentiment": {
          "negative": {
              "average_score": 0.25317941321267023,
              "count": 20
          },
          "positive": {
              "average_score": 0.5504188140233358,
              "count": 3
          },
          "neutral": {
              "average_score": 0.17684399925849653,
              "count": 22
          }
      }
  },
  {
      "keyword": "Elon Musk",
      "date": "2024-08-03T00:00:00.000Z",
      "count": 26,
    // ...
  },
  {
      "keyword": "Elon Musk",
      "date": "2024-08-09T00:00:00.000Z",
      "count": 64,
      // ...
  },
  {
      "keyword": "Elon Musk",
      "date": "2024-08-06T00:00:00.000Z",
      "count": 116,
      // ...
  }
]