FetchRSS API


Your API auth key will be here after registration.

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

Create an RSS feed. Returns a link to created feed.
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 http://facebook.com/cnn
title
optional
Set custom feed title. 120 characters max. Leave empty to fetch it from a source page automatically CNN on Facebook
description
optional
Set custom feed description. 500 characters max. Leave empty to fetch it from a source page automatically CNN news posted on Facebook
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=http%3A%2F%2Ffacebook.com%2Fcnn

Example response:

{ "success": true, "feed": { "id": "5875fec344607288628a9249", "rss_url": "http://fetchrss.com/rss/566b1cbb8a93f85e53b226f467587692067.xml" }, "target_url": "http://facebook.com/cnn" }
HTML parser
If you need to create a feed out of a general web page. You'll need to add a target page parsing selectors. It must be a CSS selectors.

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+p
Additional Facebook parameters
In addition to generic feed parameters, you can specify extra Facebook feed options. If you want to set any of these options, you must always include a "provider" parameter. Otherwise, API will ignore it.

Query parameters:

Key Required Description Example
provider
required
Must be "facebook" facebook
shared-to-original
optional
Link shared posts to the original URL
Accepted values: true / false
Default value: true
true
Additional Twitter parameters
In addition to generic feed parameters, you can specify extra Twitter feed options. If you want to set any of these options, you must always include a "provider" parameter. Otherwise, API will ignore it.

Query parameters:

Key Required Description Example
provider
required
Must be "twitter" twitter
retweets
optional
Include retweets
Accepted values: true / false
Default value: true
true
replies
optional
Include replies
Accepted values: true / false
Default value: true
true
Additional YouTube parameters
In addition to generic feed parameters, you can specify extra YouTube feed options. If you want to set any of these options, you must always include a "provider" parameter. Otherwise, API will ignore it.

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

Get a list of all user feeds

Example cURL request:

curl http://fetchrss.com/api/v1/feed/list?auth=YOUR-API-AUTH-KEY

Example response:

{ "success": true, "feeds": [ { "id": "5875fec344607288628a9249", "title": "CNN on Facebook", "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

Delete user feed
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 5875fec344607288628a9249

Example cURL request:

curl http://fetchrss.com/api/v1/feed/delete?auth=YOUR-API-AUTH-KEY&id=5875fec344607288628a9249

Example response:

{ "success": true }