Quickstart
This quick guide will get you all set up and ready to use Safron API to find yesterday's keywords and its sources to build tracking and news bots.
This is an easier use case, make sure you check out all » User Guides
Yesterday's trending keywords
Depending on what you are looking for, the first api call you may want to make is to see which keywords are trending or have been mentioned the most for a period. Here we are chosing daily, which looks at yesterday's data. You may also check keyword data for weekly, monthly, quarterly and yearly.
curl -G https://public.api.safron.io/v2/keywords \
-d period=daily \
-d slim=false
When we set slim=false, we are saying that we're interested in getting back the source ids so we can find the texts and links where the keywords were found. If you are merely using the endpoint for analysis you can remove slim=false which will set it to true.
The response we get back is all the keywords with a minimum count of 5 that were picked up yesterday. It will sort it with the trending keywords first unless otherwise specified.
Response
{
"period_chosen": "daily",
"data_to": "2024-08-12",
"keywords_found": 1131,
"keywords_returned": 100,
"sorted": "trending",
"slim_results": false,
// ...
"keywords": [
{
"keyword": "Python",
"category": "Languages & Syntax",
"trending": true,
"count": 229,
"previous_count": 141,
"change_in_count": 62,
"engagement": 3819.6616,
// ...
"sources": [
"1eqp9rl-t2_8xai8u7s_c2",
// ...
]
},
{
"keyword": "AI",
"category": "Subjects",
"trending": true,
"count": 194,
// ...
"sources": [
"1eqkc9t-t2_4nct4",
// ...
]
},
{
"keyword": "Apple",
"category": "Companies & Organizations",
"trending": true,
"count": 119,
// ...
"sources": [
"wtc-1723460149003",
// ...
]
},
{
"keyword": "Go",
"category": "Languages & Syntax",
"trending": true,
"count": 83,
// ...
"sources": [
"1eqgs78-t2_7sae3uo3_c7",
// ...
]
},
{
"keyword": "YouTube",
"category": "Websites & Applications",
"trending": true,
"count": 58,
// ...
"sources": [
"452c9c8f4be4",
// ...
]
},
{
"keyword": "Patreon",
"category": "Platforms & Search Engines",
"trending": true,
"count": 58,
// ...
"sources": [
"1eqiok9-t2_2uwit82z_c3",
// ...
]
},
// [500 more]
]
}
As you can see, the system above picked up over 1,000 keywords that has a minimum count of 5 for this day. Then it returns the exact keywords and its data as objects, with sentiment, count and engagement numbers.
The idea is that you query this endpoint daily to see what is happening without having to read or scout on your own. Below we'll understand how to get out what people are saying for keywords we are interested in.
If you are wondering what the metrics mean please see Q&A » Metrics
Get sources for a keyword
After calling the keywords endpoint we now have source ids for each keyword in each keyword object. Here we need to pick a keyword we're interested into looking in further.
Let's go with Apple, the company. Do scroll up to see its metrics from the previous response. Right now we'll grab some ids that we got back from the "sources".
curl -X POST "https://public.api.safron.io/v2/sources" \
-H "Content-Type: application/json" \
-d '{"ids": ["41224853-miiiiiike", "1eqiok9-t2_2uwit82z", "b4ac3314eb14"]}'
Remember for each keyword we got back from the keywords endpoint there was an array of "sources", here I have picked out just three ids, you should use all the source ids for the keyword.
You can query keywords and the period without the source ids to get back sources See sources endpoint »
When we get a response from the api call above it will look like this.
Response
{
"data_updated": "2024-08-13",
"sort": "engagement",
"articles": [
{
"id": "41224853-miiiiiike",
"published": "2024-08-12T14:34:46.000Z",
"type": "post",
"text": "Apple's requirements are about to hit creators and fans on Patreon",
"sentiment": "neutral",
"source": "HackerNews",
"engagement": "high",
"link": "https://news.ycombinator.com/item?id=41224853"
},
{
"id": "1eqiok9-t2_2uwit82z",
"published": "2024-08-12T16:45:55.000Z",
"type": "post",
"text": "Apple Requiring Patreon to Use In-App Purchase and Pay 30% Fee for Memberships ",
"sentiment": "neutral",
"source": "Reddit",
"engagement": "medium",
"link": "https://reddit.com/r/technews/comments/1eqiok9/apple_requiring_patreon_to_use_inapp_purchase_and/"
},
{
"id": "b4ac3314eb14",
"published": "2024-08-12T03:06:33.000Z",
"type": "post",
"text": "Apple Just Quietly Exposed The *AI Prompts* Powering Apple Intelligence I never thought “do not hallucinate” works.",
"sentiment": "neutral",
"source": "Medium.com",
"engagement": "low",
"link": "https://medium.com/macoclock/apple-just-quietly-exposed-the-ai-prompts-powering-apple-intelligence-b4ac3314eb14"
},
// ...
]
}
From here you can programmatically build a system to fetch the keywords you are interested in, and their sources, summarize them for you and send you an update.
With the source endpoint you can do more than simply get back the sources for ids, you can do keyword and plain search directly along with setting up filters for negative texts, texts with only high engagement or texts coming from a specific source.
What's next?
Great, you're now set up to be able to do something very simple with Safron. If you're keen to understand what more you can do check out all the endpoints you can use.