General information
This API provides a programmatic access to basic FetchRSS functionality.
All API requests must be sent via HTTP(S) protocol to specific endpoints using the GET method. The requested URL should look like this:
http://fetchrss.com/api/v1/ENDPOINT?auth=YOUR-API-AUTH-KEY&OTHER-PARAMETERS
Each API request must be authenticated by adding ?auth=YOUR-API-AUTH-KEY
to a query parameters.
YOUR-API-AUTH-KEY - is your personal key. It can be found at the top of this page.
The API returns JSON-encoded objects. And every response body always has a status field with a "success: true/false" value indicating any errors. If errors occur, the response will also contain an "error" object with "message" and "code" fields.
Example:
{ "success": false, "error": { "message": "Not authorised", "code": 401 } }
Limitation: All API endpoints have 1 request per second
rate limit.
For example, if you make multiple calls to the /feed/create endpoint at the same time, then only the first call will work.
And the rest will be declined.
End-Points
/feed/create
Once you've created a feed, you don't need to call this endpoint to update it. The feed is updating automatically and available at the "rss_url" address.
If you have a feed and try to create a new one with the same parameters, it won't be created. Our API will return the feed id and the rss_url of the previously created feed in this case.
Limitation: If you continue trying to create the same feed too many times, our system may block your API key. To prevent this from happening please follow two simple steps:
- Don't send a new "create" request if you already have a feed for this URL (consider keeping track of exists feeds on your side or check your feeds list with /feed/list endpoint to prevent unnecessary requests.)
- Stop attempts to create a feed for the same URL after a few fail responses.
Query parameters:
Key | Required | Description | Example |
url
|
required
|
Target URL | https://www.youtube.com/c/vsauce1 |
title
|
optional
|
Set custom feed title. 120 characters max. Leave empty to fetch it from a source page automatically | Vsauce on YouTube |
description
|
optional
|
Set custom feed description. 500 characters max. Leave empty to fetch it from a source page automatically | Vsauce recently uploaded videos |
items-per-rss
|
optional
|
Limit the number of posts in the RSS file at a time. Accepted values: 1 - 5. Default value: maximum number allowed by the current plan | 3 |
Example cURL request:
curl http://fetchrss.com/api/v1/feed/create?auth=YOUR-API-AUTH-KEY&url=https%3A%2F%2Fwww.youtube.com%2Fc%2Fvsauce1Example response:
{ "success": true, "feed": { "id": "6304a8c9431bef7af66eb704", "rss_url": "http://fetchrss.com/rss/566b1cbb8a93f85e53b226f467587692067.xml" }, "target_url": "https://www.youtube.com/c/vsauce1" }Query parameters:
Key | Required | Description | Example |
url
|
required
|
Target URL | https://www.nobelprize.org/ |
news-selector
|
required
|
News DOM selector Note: All other selectors must be inside of this DOM |
div.row > div.columns |
title-selector
|
required
|
News title selector | div.row > div.columns > h2 |
content-selector
|
required
|
News summery selector | div.row > div.columns > p |
pic-selector
|
optional
|
News illustration selector | |
date-selector
|
optional
|
News publish date selector | |
author-selector
|
optional
|
News author selector | |
link-selector
|
optional
|
News link selector | |
pic-src-param
|
optional
|
Image URL attribute. In case the page uses lazy loading images. And the required URL is not in "src" attribute |
data-src |
date-format-param
|
optional
|
Date parsing pattern See http://fetchrss.com/docs/dateParse for more details |
Y/M/D |
Example cURL request:
curl http://fetchrss.com/api/v1/feed/create?auth=YOUR-API-AUTH-KEY&url=https%3A%2F%2Fwww.nobelprize.org%2F&news-selector=div.row+%3E+div.columns&title-selector=div.row+%3E+div.columns+%3E+h2&content-selector=div.row+%3E+div.columns+%3E+pQuery parameters:
Key | Required | Description | Example |
provider
|
required
|
Must be "facebook" | |
shared-to-original
|
optional
|
Link shared posts to the original URL Accepted values: true / false Default value: true |
true |
Query parameters:
Key | Required | Description | Example |
provider
|
required
|
Must be "youtube" | youtube |
video
|
optional
|
Video in feed Accepted values: image / player / link / none Default value: player |
player |
/feed/list
Example cURL request:
curl http://fetchrss.com/api/v1/feed/list?auth=YOUR-API-AUTH-KEYExample response:
{ "success": true, "feeds": [ { "id": "6304a8c9431bef7af66eb704", "title": "Vsauce - YouTube", "rss_url": "http://fetchrss.com/rss/566b1cbb8a93f85e53b226f467587692067.xml", "src_url": "http://facebook.com/cnn" }, { "id": "587601d3446072e9628a9249", "title": "Nobelprize.org", "rss_url": "http://fetchrss.com/rss/566b1cbb8a93f85e53b226f496051329546.xml", "src_url": "https://www.nobelprize.org/" } ] }/feed/delete
Limitation: creating and then deleting the same feed too many is forbidden. Our system may block your API key if it detects such activity.
Query parameters:
Key | Required | Description | Example |
id
|
required
|
RSS ID | 6304a8c9431bef7af66eb704 |