Create a Feed from a Keyword

Fresh

RSS.app can generate RSS feeds from keyword searches and news headline topics, allowing you to track any subject across the web without targeting a specific website. This SOP covers both the keyword search method and the news headlines variant.

Two Keyword-Based Methods

Both methods use the same POST /v1/feeds endpoint but with different payloads:

Method	Body	Result
Keyword search	{ keyword, region }	Aggregated results matching the search term
News headlines	{ keyword, region } with full headline phrase	Full news stories for a specific story

The difference is in how you phrase the keyword value. A short, broad term like "solar energy" returns keyword search results. A full news headline like "NASA announces new moon mission timeline" pulls stories about that specific headline.

Prerequisites

• RSS.app account with API access enabled
• API Key and Secret (see Authentication)
• Node.js with axios installed

Step 1: Choose Your Keyword and Region

The keyword field is a search term. The region field is a two-letter country code (e.g., us, gb, au) that scopes results to news sources in that region. Use us for US English results.

Good keyword examples:

• "electric vehicles" — broad topic feed
• "Next.js 15 release" — specific topic
• "Miami real estate market" — geo-scoped topic
• "TypeScript 5.0 features" — product news

Step 2: Create a Keyword Feed

const axios = require('axios');

const apiClient = axios.create({
  baseURL: 'https://api.rss.app/v1',
  headers: {
    Authorization: `Bearer YOUR_API_KEY:YOUR_API_SECRET`,
    'Content-Type': 'application/json',
  },
});

async function createKeywordFeed(keyword, region = 'us') {
  const response = await apiClient.post('/feeds', {
    keyword,
    region,
  });
  return response.data;
}

// Example: track AI news in the US
createKeywordFeed('artificial intelligence', 'us')
  .then((feed) => {
    console.log('Feed ID:', feed.id);
    console.log('RSS URL:', feed.rss_feed_url);
    console.log('Items found:', feed.items.length);
  })
  .catch((err) => console.error(err.response?.data || err.message));

Step 3: Create a News Headlines Feed

For a specific news story, provide the full headline as the keyword. This method aggregates multiple publications covering the same story, giving you broader coverage of a single news event.

async function createHeadlineFeed(headline, region = 'us') {
  const response = await apiClient.post('/feeds', {
    keyword: headline,
    region,
  });
  return response.data;
}

// Example: track a specific news story
createHeadlineFeed('Federal Reserve raises interest rates quarter point', 'us')
  .then((feed) => {
    console.log('Feed ID:', feed.id);
    console.log('Title:', feed.title);
    console.log('Coverage items:', feed.items.length);
  })
  .catch((err) => console.error(err.response?.data || err.message));

Step 4: Understand the Response

The response structure is the same for both keyword and headline feeds:

{
  "id": "feed_kw456",
  "title": "artificial intelligence",
  "source_url": null,
  "rss_feed_url": "https://rss.app/feeds/your-feed-id.xml",
  "description": "News and updates about artificial intelligence",
  "icon": null,
  "is_active": true,
  "items": [
    {
      "url": "https://publisher.com/article",
      "title": "OpenAI Releases New Model",
      "description_text": "OpenAI today announced...",
      "description_html": "<p>OpenAI today announced...</p>",
      "thumbnail": "https://publisher.com/image.jpg",
      "authors": [{ "name": "Jane Reporter" }],
      "date_published": "2024-01-15T14:00:00Z"
    }
  ]
}

Note that source_url may be null for keyword feeds since there is no single origin website.

Step 5: Store the Feed for Retrieval

async function createKeywordFeedWithStorage(keyword, region, db) {
  const feed = await createKeywordFeed(keyword, region);

  await db.feeds.insert({
    externalId: feed.id,
    type: 'keyword',
    keyword: keyword,
    region: region,
    rssFeedUrl: feed.rss_feed_url,
    createdAt: new Date(),
  });

  return feed;
}

Supported Region Codes

Use standard ISO 3166-1 alpha-2 country codes. Common values:

Code	Region
us	United States
gb	United Kingdom
au	Australia
ca	Canada
in	India
de	Germany
fr	France

Tips for Better Results

Be specific with keywords. "roofing contractor Miami" returns more relevant results than just "roofing". Include location, product name, or topic qualifier to narrow the feed content.

Match the region to the language. If you're building a Spanish-language feed, use region codes for Spanish-speaking countries (es, mx, ar) so the results are in the right language.

Headline feeds work best with timely stories. Use the full headline as it appears in major publications. Paraphrasing can reduce the coverage you get back.

Use keyword feeds for ongoing monitoring. Keyword feeds continue to update as new articles matching the term are published. They are better suited for continuous monitoring than one-time scrapes.

Error Handling

async function createKeywordFeedSafely(keyword, region) {
  try {
    const feed = await createKeywordFeed(keyword, region);
    return { success: true, feed };
  } catch (err) {
    const status = err.response?.status;
    if (status === 400) {
      return { success: false, reason: 'Invalid keyword or region parameter' };
    }
    if (status === 402) {
      return { success: false, reason: 'Feed creation limit reached for your plan' };
    }
    if (status === 429) {
      return { success: false, reason: 'Rate limit exceeded — slow down requests' };
    }
    return { success: false, reason: err.response?.data?.message || err.message };
  }
}