FreshRSS/docs/en/developers/06_GoogleReader_API.md

FreshRSS - Google Reader compatible API implementation

See Mobile access for general aspects of API access.

See also the page about our Fever compatible API for another possibility (less powerful).

RSS clients

There are many RSS clients that support the Fever API, but they might understand the API a bit differently. If your favourite client doesn’t work properly with this API, please create an issue and we’ll have a look. But we can only do that for free clients.

Usage & Authentication

Before you can start using this API, you have to enable and setup API access, which is documented here, and then reset the user’s API password.

Then point your mobile application to the greader.php address (e.g. https://freshrss.example.net/api/greader.php).

Compatible clients

1. On the same FreshRSS API page, note the address given under “Your API address”, like https://freshrss.example.net/api/greader.php
2. Type the API address in a client, together with your FreshRSS username, and the corresponding special API password.

App	Platform	License
News+ with News+ Google Reader extension	Android	Closed Source (Free), partially open source
FeedMe 3.5.3+	Android	Closed Source (Free)
EasyRSS	Android	GPLv3 (F-Droid)
Readrops	Android	GPLv3
Fluent Reader Lite	Android, iOS	BSD-3
Read You	Android	GPLv3
FocusReader	Android	Closed Source(Free)
Newsflash	Linux	GPLv3
lire	iOS, macOS	Closed Source
Newsboat 2.24+	Linux	MIT
Vienna RSS	macOS	Apache-2.0
Reeder Classic	macOS, iOS	Closed Source
FreshRSS-Notify	Firefox	Open Source

ℹ️ See a better table of compatible clients in our main Readme.

Google Reader compatible API

Examples of basic queries:

# Initial login, using API password (Email and Passwd can be given either as GET, or POST - better)
curl 'https://freshrss.example.net/api/greader.php/accounts/ClientLogin?Email=alice&Passwd=Abcdef123456'
SID=alice/8e6845e089457af25303abc6f53356eb60bdb5f8
Auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8

# Examples of read-only requests
curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
  'https://freshrss.example.net/api/greader.php/reader/api/0/subscription/list?output=json'

curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
  'https://freshrss.example.net/api/greader.php/reader/api/0/unread-count?output=json'

curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
  'https://freshrss.example.net/api/greader.php/reader/api/0/tag/list?output=json'

# Retrieve a token for requests making modifications
curl -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
  'https://freshrss.example.net/api/greader.php/reader/api/0/token'
8e6845e089457af25303abc6f53356eb60bdb5f8ZZZZZZZZZZZZZZZZZ

# Get articles, piped to jq for easier JSON reading
curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
  'https://freshrss.example.net/api/greader.php/reader/api/0/stream/contents/reading-list' | jq .

# Unsubscribe from a feed
curl -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
  -d 'ac=unsubscribe&s=feed/52' 'https://freshrss.example.net/api/greader.php/reader/api/0/subscription/edit'

• Source code of our API implementation

API documentation from the original Google Reader

• By Daniel Arowser (source)
• By Martin Doms
• By Nick Bradbury
• By Niall Kennedy
• By Mihai Parparita (source)

API documentation from other compatible servers

• FeedHQ
• Inoreader
• The Old Reader
• pyrfeed
• BazQux

Synchronisation strategy

ℹ️ If you are maintaining a client or planning to develop a new one, please read carefully the following pieces of advice, as many clients start by having a very inneficient synchronisation strategy.

• Synchronisation recommendation by Alkarex
• Additional synchronisation tips by Alkarex
• The Right Way to Sync by BazQux