Sources

The sources endpoint will act as a search database. It is where we store all the sources for the keyword data in all the other endpoints. It may be used in isolation to get back different sources for a keyword to do research.

Sources Endpoint

The sources endpoint will need keywords, ids or a search string. You will use the ids you get back from the expanded views in the keywords, graph and connected-keywords endpoints. You may also search the entire database with an exact phrase. It will then give you back the sources we've found.

Properties (Requires one)

Name
ids
Type
array
Description
Provide and array with ids to get the exact matches.
Name
keywords
Type
array
Description
Provide and array with strings to get the exact matches.
Name
search
Type
string
Description
Provide a search string to search for matches.

POSTpublic.api.safron.io/v2/sources

Public v2

This endpoint allows you to retrieve sources based on ids, keywords or a search string.

Requires at least one attribute

Name
ids
Type
array
Description
Provide and array with ids to get the exact matches.
Name
keywords
Type
array
Description
Provide and array with strings to get the exact matches.
Name
search
Type
string
Description
Provide a search string to search for matches.

Optional attributes

Name
slim
Type
bool
Description
Default is set to true. Set to false to increase the data returned.
Name
period
Type
string
Description
To be inline with the other endpoints, you can set the period to daily, weekly, monthly and quarterly instead of using the specific dates. You can also not specify dates or a period at all.
Name
startDate
Type
string
Description
Set the start date for data returned. Mostly relevant when you query keywords or use search. Example is 2024-01-01.
Name
endDate
Type
string
Description
Set the end date for data returned. Mostly relevant when you query keywords or use search. Example is 2024-01-30.
Name
sort
Type
string
Description
Default is set to engagement. Options are to sort based on old, new, engagement.
Name
limit
Type
integer
Description
Limit the number of sources returned. Defult is set to 25.
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
type
Type
string
Description
Set the type of mentions counted by only post (post, article, newsletter and so on) or comment.
Name
sentiment
Type
string
Description
Only get back the sources with sentiment that is specified as neutral, positive or negative.

Request

POST

/v2/sources

curl -X POST "https://public.api.safron.io/v2/sources" \
 -H "Content-Type: application/json" \
 -d '{"keywords": ["OpenAI"]}'

Response

{
    "data_updated": "2024-08-12",
    "limit": 25,
    "sort": "engagement",
    "articles_returned": 25,
    "articles": [
        {
            "id": "41168904-tzury",
            "published": "2024-08-06T08:39:55.000Z",
            "type": "post",
            "text": "OpenAI co-founder John Schulman says he will leave and join rival Anthropic",
            "sentiment": "neutral",
            "source": "HackerNews",
            "engagement": "high",
            "link": "https://news.ycombinator.com/item?id=41168904"
        },
        {
            "id": "1epe6en-t2_rpv4m",
            "published": "2024-08-11T06:33:17.000Z",
            "type": "post",
            "text": "ChatGPT unexpectedly began speaking in a user’s cloned voice during testing | \"OpenAI just leaked the plot of Black Mirror's next season.\" ",
            "sentiment": "neutral",
            "source": "Reddit",
            "engagement": "high",
            "link": "https://reddit.com/r/technews/comments/1epe6en/chatgpt_unexpectedly_began_speaking_in_a_users/"
        },
        // ...
      ]
}

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

POSTprivate.api.safron.io/v2/sources

Private v2

This private endpoint allows you to retrieve sources based on ids, keywords or a search string. It does not have rate limits and you may query more than 25 results at a time.

Requires at least one attribute

Name
ids
Type
array
Description
Provide and array with ids to get the exact matches.
Name
keywords
Type
array
Description
Provide and array with strings to get the exact matches.
Name
search
Type
string
Description
Provide a search string to search for matches.

Optional attributes

Name
slim
Type
bool
Description
Default is set to true. Set to false to increase the data returned.
Name
period
Type
string
Description
To be inline with the other endpoints, you can set the period to daily, weekly, monthly and quarterly instead of using the specific dates. You can also not specify dates or a period at all.
Name
startDate
Type
string
Description
Set the start date for data returned. Mostly relevant when you query keywords or use search. Example is 2024-01-01.
Name
endDate
Type
string
Description
Set the end date for data returned. Mostly relevant when you query keywords or use search. Example is 2024-01-30.
Name
sort
Type
string
Description
Default is set to engagement. Options are to sort based on old, new, engagement.
Name
limit
Type
integer
Description
Limit the number of sources returned. Defult is set to 25.
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
type
Type
string
Description
Set the type of mentions counted by only post (post, article, newsletter and so on) or comment.
Name
sentiment
Type
string
Description
Only get back the sources with sentiment that is specified as neutral, positive or negative.

Request

POST

/v2/sources

curl -X POST "https://private.api.safron.io/v2/sources" \
 -H "x-api-key": {API_Key} \
 -H "Content-Type: application/json" \
 -d '{"keywords": ["OpenAI"]}'

Response

{
    "data_updated": "2024-08-12",
    "limit": 25,
    "sort": "engagement",
    "articles_returned": 25,
    "articles": [
        {
            "id": "41168904-tzury",
            "published": "2024-08-06T08:39:55.000Z",
            "type": "post",
            "text": "OpenAI co-founder John Schulman says he will leave and join rival Anthropic",
            "sentiment": "neutral",
            "source": "HackerNews",
            "engagement": "high",
            "link": "https://news.ycombinator.com/item?id=41168904"
        },
        {
            "id": "1epe6en-t2_rpv4m",
            "published": "2024-08-11T06:33:17.000Z",
            "type": "post",
            "text": "ChatGPT unexpectedly began speaking in a user’s cloned voice during testing | \"OpenAI just leaked the plot of Black Mirror's next season.\" ",
            "sentiment": "neutral",
            "source": "Reddit",
            "engagement": "high",
            "link": "https://reddit.com/r/technews/comments/1epe6en/chatgpt_unexpectedly_began_speaking_in_a_users/"
        },
        // ...
      ]
}

POSTsafron.io/api/sources

Public v1

This public endpoint allows you to retrieve sources based on ids or keywords. It is a first version and now depreciated.

Requires at least one attribute

Name
ids
Type
array
Description
Provide and array with ids to get the exact matches.
Name
keywords
Type
array
Description
Provide and array with strings to get the exact matches.

Optional attributes

Name
startDate
Type
string
Description
Set the start date for data returned. Mostly relevant when you query keywords or use search. Example is 2024-01-01.
Name
endDate
Type
string
Description
Set the end date for data returned. Mostly relevant when you query keywords or use search. Example is 2024-01-30.
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
type
Type
string
Description
Set the type of mentions counted by only post (post, article, newsletter and so on) or comment.
Name
sentiment
Type
string
Description
Only get back the sources with sentiment that is specified as neutral, positive or negative.

Request

POST

/v2/sources

curl -X POST "https://safron.io/api/sources" \
 -H "Content-Type: application/json" \
 -d '{"keywords": ["OpenAI"]}'

Response

{
  "articles_found": 431,
  "articles": [
    {
        "id": "41168904-tzury",
        "text": "OpenAI co-founder John Schulman says he will leave and join rival Anthropic",
        "title": "OpenAI co-founder John Schulman says he will leave and join rival Anthropic",
        "type": "post",
        "published": "2024-08-06T08:39:55.000Z",
        "source": "HackerNews",
        "medium": "New Stories",
        "keywords": [
            "OpenAI",
            "Anthropic",
            "John Schulman"
        ],
        "relevance": "high",
        "sentiment_label": "neutral",
        "sentiment_score": 0.854035496711731,
        "url": "https://news.ycombinator.com/item?id=41168904"
    },
    {
        "id": "41125630-fredski42",
        "text": "How Does OpenAI Survive?",
        "title": "How Does OpenAI Survive?",
        "type": "post",
        "published": "2024-08-01T02:18:28.000Z",
        "source": "HackerNews",
        "medium": "New Stories",
        "keywords": [
            "Survival",
            "OpenAI"
        ],
        "relevance": "high",
        "sentiment_label": "neutral",
        "sentiment_score": 0.7539235949516296,
        "url": "https://news.ycombinator.com/item?id=41125630"
    },
    // ...
  ]
}