Twingly Blog LiveFeed API v5


Blog LiveFeed API is a HTTP based API used for receiving a continuous real-time stream of blog data. To be able to retrieve data through LiveFeed, an API key issued by Twingly must be used. The API key then grants access to blog data for one or more languages. If you don’t have access, you can sign up for a free trial.

The responsibility of retrieving the data in a correct manner so that nothing is missed lies entirely on the client. To facilitate this, LiveFeed API exposes one endpoint, GetData, which is polled using a timestamp that’s extracted from the last response.

It is possible to request historic data from the LiveFeed API up to 30 days back in time.

API Endpoint

A GET request to /GetData will return posts from (and forward in time) a given timestamp. This method should be polled continuously, each time with a new timestamp from last results nextTimestamp, effectively creating a “live feed” of blog data.

Note that the input timestamp relates to when Twingly first made the data available through the LiveFeed API.

HTTP options

Request Parameters

Allowed GET parameters:

Parameter Format Example Notes
apikey String E67EFC65-08A9-4086-BE92-074BBD7F78EA Required
timestamp ISO 8601 (UTC) 2017-04-24T10:22:38.361Z Required
maxPosts Integer 1000 Optional, defaults to 1000. Maximum value is 5000.
format String xml Optional, defaults to xml (which is the only allowed value)

Example Request

Example request for the GetData method with maxPosts set to 1.

curl -s ""


The response is an XML document containing one or more posts. See below for an example and explanation of all the elements and attributes.

Note that in older versions of the LiveFeed API, the result can look different. Only the latest version is documented here.

Example response from the example request shown above.

<twinglydata ts="2017-04-25T08:33:07.053785Z" from="2017-04-24T10:22:37.354Z" numberOfPosts="1" maxNumberOfPosts="1" firstPost="2017-04-24T10:22:38.36Z" lastPost="2017-04-24T10:22:38.36Z" nextTimestamp="2017-04-24T10:22:38.361Z">
    <author>Henrik Foto</author>
    Äntligen har jag lyckats fånga norrsken på bild (här nere på 57:e breddgraden dyker det inte upp så jätteofta). Bilden är tagen inatt.
      <tag>aurora borealis</tag>
      <tag>northern lights</tag>
    <blogName>Henriks fotoblogg</blogName>

Elements and attributes:

<twinglydata> is the root element with the following attributes:

Within the root element, <twinglydata>, there can be zero or more <post> elements. Note that posts that are indexed/inserted at the same millisecond have an undefined sorting order, meaning that the same query might return documents in slightly different order.

<post> is the root element for a post and contains the following child elements:

Rate limits

We have no hard rate limits, using the same key for production, staging, and development is therefore perfectly fine. However, as this is a LiveFeed API there should not be a need for more than 1 concurrent request per stage.


We strive to respond with the correct HTTP status code and respond with valid XML. But since computers can be tricky at times, you should ensure your client don’t blow up if we give a broken response (please contact us if we do).

The errors from the API looks like this:

<error code="123">

In the GitHub repository for the Blog LiveFeed Ruby client developed by Twingly, you can find example responses for most errors documented below.

4xx Client errors

Client errors, most likely your client sending invalid requests but please contact us if you can’t figure it out.

HTTP status Error code Description
400 40001 Bad request (see the message for more info)
401 40101 Unauthorized
404 40401 Not Found

5xx Server errors

HTTP status Error code Description
500 50001 Internal Server Error. Unexpected conditions were encountered, indicating a server-side bug.
503 50301 Authentication service unavailable. Retry later.
503 50302 Service Unavailable. Retry later.

Best practices

Integration example

This shows the basics required to continuously fetch data. It’s a fully functional example in Ruby 2.4, but primary purpose is to quickly illustrate how an integration should work.

# Remember to set the environment variable key `TWINGLY_API_KEY`
require "net/http"
require "time"
require "rexml/document"

params = {
  timestamp: ( - 3600).utc.iso8601, # Start one hour ago
  apikey: ENV["TWINGLY_API_KEY"], # API key to access Blog LiveFeed

loop do
  uri = URI(BASE_URL)
  uri.query = URI.encode_www_form(params)

  Net::HTTP.get_response(uri) do |result|
    # No error handling code in this example, just stop
    break unless result.is_a?(Net::HTTPSuccess)

    document =

    # Extract post URLs, print to stdout
    document.elements.each("twinglydata/post/url") do |url_element|
      puts url_element.text

    # Extract helper attributes to control the polling
    attributes = document.root.attributes

    next_timestamp      = attributes["nextTimestamp"]
    number_of_posts     = attributes["numberOfPosts"].to_i
    max_number_of_posts = attributes["maxNumberOfPosts"].to_i

    # Update timestamp for next iteration
    params[:timestamp] = next_timestamp

    # Sleep a while if there's no more documents available
    sleep 60 if number_of_posts < max_number_of_posts

With this approach you will get a continuous stream of all the data that the API key grants access to. Of course, error handling must be added to handle network outages, server failure et cetera.

Available data

As soon as we get new blog content it will be available through the LiveFeed API. Most often it takes just a few seconds for data to flow through our system, it may be a few minutes during maintenance though.

Some notes:

See also our page about the ingestion system details and challenges.

Supported languages

Your API key can be granted access to blog data for one or more languages. These are the languages that are currently supported:

Language Code Remarks
Afrikaans af  
Albanian sq  
Arabic ar  
Bengali bn  
Bulgarian bg  
Catalan ca  
Chinese zh Includes both simplified and traditional Chinese
Croatian hr  
Czech cs  
Danish da  
Dutch nl  
English en  
Estonian et  
Finnish fi  
French fr  
Georgian ka  
German de  
Greek el  
Gujarati gu  
Hebrew he  
Hindi hi  
Hungarian hu  
Icelandic is  
Indonesian id  
Italian it  
Japanese ja  
Kannada kn  
Korean ko  
Lithuanian lt  
Macedonian mk  
Malayalam ml  
Marathi mr  
Nepali ne  
Norwegian no  
Persian fa  
Polish pl  
Portuguese pt  
Punjabi pa  
Romanian ro  
Russian ru  
Serbian sr Only the Cyrillic alphabet is supported
Slovak sk  
Slovenian sl  
Somali so  
Spanish es  
Swahili sw  
Swedish sv  
Tagalog tl  
Tamil ta  
Telugu te  
Thai th  
Turkish tr  
Ukrainian uk  
Urdu ur  
Vietnamese vi  
Welsh cy  

Known issues


Changes from previous version

We have focused on simplifying the API request and extending the response.

Changes to output XML:

Migrating from LiveFeed v4

These are the minimum required steps to move from v4 to v5:

Then you should get the same functionality as before, but feel free to utilize the new data now provided by Twingly Blog LiveFeed API v5.

Documentation changelog

API changelog