Keywords

The keywords endpoint is designed to collect data, and then aggregate it handing you the top and trending keywords for a period within tech. This is a way to get an overview what is happening day to day. When connected to the sources endpoint it is also a way to get customized news.

Keywords Endpoint

To use this endpoint you'll have to consider the period you want to query, having access to 5 different periods, daily, weekly, monthly, quarterly and yearly. Data is always collected until 2 AM for the preceeding day before it starts processing. This means that if you pick the daily period, you get data up to 23.59 PM the day before (i.e. yesterday' data).

The data is sorted by category, which isn't required when calling the API but it will significantly speed up the request if you specify what you are interested in.

How do we categorize keywords? We have 12 different categories, that are Companies & Organizations, Tools & Services, Platforms & Search Engines, Hardware & Systems, Frameworks & Libraries, Languages & Syntax, AI Models & Assistants, Websites & Applications, People, Subjects, Concepts & Methods, and Bucket (other) Understand Categories » Q&A.

Lastly, you have to decide if you are only interested in statistics, then it may do to simply get the amount of trending keywords for a category and skip getting the ids back for the sources.

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
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/keywords

Public v2

This endpoint allows you to retrieve keyword data for a specific endpoint based on a period.

This endpoint is public which means it uses a shared cluster to gather reports. It has access to daily, weekly, monthly and quarterly reports.

Required attributes

Name
period
Type
string
Description
Set the period to daily, weekly or monthly. The period will look at the preceeding period to calculate differences in statistics.
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.

Optional attributes

Name
sort
Type
string
Description
Sort is set as trending by default. You may set it as top, trending, alphabetical-a or alphabetical-z.
Name
limit
Type
integer
Description
Limit is set to 100 keywords by default, you may expand this to up to 2000.
Name
category
Type
string
Description
Set the category for the keyword data returned. Available categories are companies, ai, tools, platforms, hardware, people, frameworks, languages, concepts, websites and subjects. Understand Categories » Q&A
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
sentiment
Type
string
Description
Only get back the keywords with a majority sentiment that is specified as neutral, positive or negative. Remember that you can expand the results to get the count of each sentiment using slim=false parameter instead if you want to see the count for each sentiment per keyword instead.
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
search
Type
bool
Description
Search for a keyword in the results. Interesting if you are looking at the statistics for only one keyword.
Name
irrelevant
Type
bool
Description
Default is set to true which excludes keywords that have been categorized in the Bucket (other) category. You may specify this as false to include any keyword regardless if it is relevant or not.
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/keywords

curl -G https://public.api.safron.io/v2/keywords \
  -d period=daily \
  -d slim=true

Response

{
  "period_chosen": "daily",
  "data_to": "2024-08-26",
  "keywords_found": 1131,
  "keywords_returned": 100,
  "sorted": "trending",
  "slim_results": true,
  "keywords": [
      {
        "keyword": "AI",
        "category": "Subjects",
        "trending": true,
        "count": 303,
        "previous_count": 193,
        "change_in_count": 57,
        "engagement": "high",
        "change_in_engagement": "positive",
        "sentiment": "neutral",
        "change_in_sentiment": false
    },
    {
        "keyword": "Uber",
        "category": "Companies & Organizations",
        "trending": true,
        "count": 63,
        "previous_count": 0,
        "change_in_count": 6300,
        "engagement": "high",
        "change_in_engagement": "positive",
        "sentiment": "negative",
        "change_in_sentiment": false
    },
    {
        "keyword": "China",
        "category": "Subjects",
        "trending": true,
        "count": 52,
        "previous_count": 20,
        "change_in_count": 160,
        "engagement": "medium",
        "change_in_engagement": "positive",
        "sentiment": "neutral",
        "change_in_sentiment": true
    },
    // ...
  ]
}

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

GETprivate.api.safron.io/v2/keywords

Private v2

This endpoint allows you to retrieve keyword data for a specific endpoint based on a period. It will need an API key but has no limits on usage.

This endpoint is private which means it is faster and more accessible. It has access to daily, weekly, monthly, quarterly, yearly reports.

Required attributes

Name
period
Type
string
Description
Set the period to daily, weekly, monthly, quarterly or yearly. The period will look at the preceeding period to calculate differences in statistics. To speed up response time please set a category as well.
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.

Optional attributes

Name
sort
Type
string
Description
Sort is set as trending by default. You may set it as top, trending, alphabetical-a or alphabetical-z.
Name
limit
Type
integer
Description
Limit is set to 100 keywords by default, you may expand this to up to 2000.
Name
category
Type
string
Description
Set the category for the keyword data returned. Available categories are companies, ai, tools, platforms, hardware, people, frameworks, languages, concepts, websites and subjects. Understand Categories » Q&A
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
string
Description
Set the specific source you want the data to orginate from. Some choices are hackernews, reddit, devto and github and so on.
Name
sentiment
Type
string
Description
Only get back the keywords with a majority sentiment that is specified as neutral, positive or negative. Remember that you can expand the results to get the count of each sentiment using slim=false parameter instead if you want to see the count for each sentiment per keyword instead.
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
search
Type
bool
Description
Search for a keyword in the results. Interesting if you are looking at the statistics for only one keyword.
Name
irrelevant
Type
bool
Description
Default is set to true which excludes keywords that have been categorized in the Bucket (other) category. You may specify this as false to include any keyword regardless if it is relevant or not.
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/keywords

curl -G https://private.api.safron.io/v2/keywords \
  -H x-api-key: {API_Key} \
  -d period=daily \
  -d slim=true

Response

{
  "period_chosen": "daily",
  "data_to": "2024-08-26",
  "keywords_found": 1131,
  "keywords_returned": 100,
  "sorted": "trending",
  "slim_results": true,
  "keywords": [
      {
        "keyword": "AI",
        "category": "Subjects",
        "trending": true,
        "count": 303,
        "previous_count": 193,
        "change_in_count": 57,
        "engagement": "high",
        "change_in_engagement": "positive",
        "sentiment": "neutral",
        "change_in_sentiment": false
    },
    {
        "keyword": "Uber",
        "category": "Companies & Organizations",
        "trending": true,
        "count": 63,
        "previous_count": 0,
        "change_in_count": 6300,
        "engagement": "high",
        "change_in_engagement": "positive",
        "sentiment": "negative",
        "change_in_sentiment": false
    },
    {
        "keyword": "China",
        "category": "Subjects",
        "trending": true,
        "count": 52,
        "previous_count": 20,
        "change_in_count": 160,
        "engagement": "medium",
        "change_in_engagement": "positive",
        "sentiment": "neutral",
        "change_in_sentiment": true
    },
    // ...
  ]
}

GETsafron.io/api/table

Public v1 (Depreciated)

Depreciated endpoint for keyword data.

Required attributes

Name
period
Type
string
Description
Set the period to daily or weekly. The period will look at the preceeding period to calculate differences in statistics.

Optional attributes

Name
sort
Type
string
Description
Sort is set as trending by default. You may set it as top or trending.
Name
category
Type
string
Description
Set the category for the keyword data returned. Available categories are companies, ai, tools, platforms, hardware, people, frameworks, languages, concepts, websites and subjects. Understand Categories » Q&A
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/table

curl https://safron.io/api/table \
  -d period=daily \

Response

{
  "update_date": "2024-08-12",
  "rows": 1077,
  "results": [
      {
          "keyword": "Python",
          "date": "2024-08-12T00:00:00.000Z",
          "count": 229,
          "category": "Languages & Syntax",
          "row_ids": [
              "1eqp9rl-t2_8xai8u7s_c2",
              // ...
          ],
          "sentiment": {
              "negative": {
                  "average_score": 0.20370563962292232,
                  "count": 47
              },
              "positive": {
                  "average_score": 0.2476629337948612,
                  "count": 78
              },
              "neutral": {
                  "average_score": 0.17919093813742618,
                  "count": 104
              }
          },
          "yesterday_count": 141,
          "sentiment_previous": {
              "negative": {
                  "average_score": 0.19666522999604544,
                  "count": 30
              },
              "positive": {
                  "average_score": 0.3714247084624985,
                  "count": 38
              },
              "neutral": {
                  "average_score": 0.16747426420003078,
                  "count": 73
              }
          },
          "countChange": 62.4113475177305,
          "trending": true,
          "engagement": 3819.6616
      },
      // ..
    ]
}