Feed History API documentation version 0.1dev2

https://feedhistory.api.ce-traffic.com/0.1dev2

Introduction

This API allows browsing and fetching historical versions of feeds as published by CE-Traffic a.s.

As it is API, it expects use by a programmer, who can handle using JSON and some kind of programmable HTTP client.

In many cases responses are available also with text/plain content type. You shall send the request with header Accept:text/plain to get it instead of default application/json.

Content type of final fetched feed version may vary per feed type, initial feeds are text/xml and are using Content-Encoding:gzip.

The API is serving final fetched feed version by sending redirect to so called temporary url. This url allows fetching real content and is valid for limited time (typically 10 minutes). If you configure your client to "follow redirect", you shall get the content automatically (the client shall make the second request to temporary url automatically.). However, this is client dependent and API has no way to affect such behaviour.

API uses Basic Authentication over https. Note, that examples below use user demo with password pswd, which are intentionally invalid. Use credentials you got from API provider.

Access to latest API specification

Accessing root of domain (without version) shall show api.html page.

  • {domain} - shows {domain}/api.html
  • {domain}/api.html - HTML form of spec. This is default
  • {domain}/api.raml - RAML form of specification.

api.raml is YAML file. You shall be able fetching information about endpoint url from here.

Access to latest API specification

Consider versions with dev suffix work in progress.

We plan to run only latest version of our API.

version 0.1dev2 - API spec published

  • Added API specification in RAML and HTML format

version 0.1dev (1) - Basic authentication

  • Added Basic Authentication

version 0.1dev - initial published version

Initial version.

  • Browse feeds/days/versions + fetch content via redirect
  • Get versions in date-time interval
  • Get feed content for approximate date-time
  • No authentication

Quick Start

Use curl to learn about available feed types.

$ curl --insecure https://feedhistory.api.ce-traffic.com/0.1dev2/feeds
curl --insecure -u demo:pswd https://feedhistory.api.ce-traffic.com/0.1dev2/feeds
[
{
    "id": "pl-DataFusionService.xml",
    "days_url": "https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days"
},
{
    "id": "cz-DataFusionService.xml",
    "days_url": "https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/cz-DataFusionService.xml/days"
}
]

Default content type is application/json, you may use header Accept:text/plain to get only urls:

$ curl --insecure -u demo:pswd -H Accept:text/plain https://feedhistory.api.ce-traffic.com/0.1dev2/feeds
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/cz-DataFusionService.xml/days

Use these urls to get list of all days for first of the feeds:

$ curl --insecure -u demo:pswd -H Accept:text/plain https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150523/versions
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150524/versions
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150525/versions
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150526/versions
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150527/versions
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150528/versions
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150529/versions
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150530/versions
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150531/versions
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150601/versions
...

Fetch all versions for one of the days (for feeds published once a minute there are about 1440 versions a day):

$ curl --insecure -u demo:pswd -H Accept:text/plain https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150524/versions
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150524/versions/000109-0285f
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150524/versions/000210-00569
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150524/versions/000310-fee0d
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150524/versions/000406-6e2d2
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150524/versions/000507-047c2
...

To fetch real feed version, use any of the urls. Using "follow redirect" allows getting the content after initial redirection from the API. This time there is no need to use plain/text header:

$ curl --insecure -u demo:pswd -O https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150524/versions/000109-0285f

This shall create file named 000109-0285f in current directory.

WARNING: Names of saved files do not contain date, so fetching multiple days into one directory can create a mess. Better save each day into separate directory.

Directly fetching single feed version close to known date-time

If you know feed name (e.g. pl-DataFusionService) and approximate date-time, you may try first endpoint to fetch just one version.

$ curl -O --insecure -u demo:pswd --location https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/first/2015-05-24T12

Given date-time string is similar to ISO 8601 syntax and can be shortened (but must always contain at least full date). For more see "Flexible date-time format" section.

Fetching versions for defined time interval

We can also get list of feed versions across days. Time interval is expressed by means of two flexible date-time strings:

$ curl --insecure -u demo:pswd -H Accept:text/plain https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/versions/2015-05-24T23/2015-05-25T04
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150524/versions/230157-6f9e2
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150524/versions/230246-30f43
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150524/versions/230349-0bede
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150524/versions/230452-059a2
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150524/versions/230546-210f7
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150524/versions/230646-f679d
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150524/versions/230750-a211b
..........
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150525/versions/003315-bf89d
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150525/versions/003414-e8ece
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150525/versions/003516-629ec
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150525/versions/003620-0d1e9
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150525/versions/003723-385df
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150525/versions/003813-db35d
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150525/versions/003912-dbda2

In case, number of versions exceed 999, only 999 urls are returned. If you want to get following "page", use url, returned in "Link" header of the response.

Few programming tips

Here are few tips for programming script, fetching feeds.

  • Default content encoding is application/json. Use that.
  • JSON response for fetching one version contains proposed name of file for saving the content. e.g. "pl-DataFusionService-20150525-003912-dbda2.xml". Do not follow redirect, read this file name and use url in the response to do final fetch.

Flexible date-time format

Some arguments are using so called flexible date-time format.

This section describes this type.

Date time is expressed as a string following these rules:

  • expressed in UTC
  • base format is YYYY-MM-DDTHH:MM:SS
  • all non-numeric characters can be omited
  • it can be shortened, but the date must be always preserved as is. Remaining time part is then zero-padded.

The string can be shortened on right side (then it denotes earliest moment with such start).

ValueReal meaning
2015invalid
2015-11invalid
2015-11-1invalid
2015-11-142015-11-14T00:00:00Z
2015-11-14T102015-11-14T10:00:00Z
2015-11-14T10:52015-11-14T10:50:00Z
2015-11-14T10:05:062015-11-14T10:05:06Z
20151114102015-11-14T10:00:00Z
201511141052015-11-14T10:50:00Z
2015-11-14T10052015-11-14T10:05:00Z
2015-11-14T1005062015-11-14T10:05:06Z

/feeds

get

get

List available feeds

get

Days for which given feed has some versions

get

List days for which exist some feed versions

List days for which exist some feed versions

Secured by basic

URI Parameters

  • feed: required (string)

    feed identifier in form of text

Headers

  • accept: (one of application/json, text/plain)

HTTP status code 200

Body

Type: application/json

Example:


[
  {
      "day_versions_url": "https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150522/versions",
      "id": "20150522"
  },
  {
      "day_versions_url": "https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150523/versions",
      "id": "20150523"
  },
  {
      "day_versions_url": "https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150524/versions",
      "id": "20150524"
  }
    
]

Type: text/plain

Example:

https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150522/versions
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150523/versions
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150524/versions
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150525/versions
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150526/versions

HTTP status code 404

Feed with given name not found

get

time based version identifiers of available feed versions

get

List feed versions for given date

List feed versions for given date

Secured by basic

URI Parameters

  • feed: required (string)

    feed identifier in form of text

  • date: required (string - pattern: ^[0-9]{8}$)

    (UTC based) date in format YYYYMMDD

Headers

  • accept: (one of application/json, text/plain)

HTTP status code 200

Body

Type: application/json

Example:

[
  {
      "id": "141131-dd7d8",
      "version_url": "https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150522/versions/141131-dd7d8"
  },
  {
      "id": "141223-42628",
      "version_url": "https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150522/versions/141223-42628"
  },
  {
      "id": "141331-f297f",
      "version_url": "https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150522/versions/141331-f297f"
  }
]

Type: text/plain

Example:

https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150522/versions/141131-dd7d8
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150522/versions/141223-42628
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150522/versions/141331-f297f

HTTP status code 404

Feed with given name not found

get

get

Get feed version.

Note: Content type may vary {feed} by {feed}

Warning: Some feeds are large. When retrieved from web browser, it may got frozen as browsers are often trying to render the (large) content.

Warning: Target domain uses https protocol and some clients complain about invalid ssl certificate.

Get feed version.

Note: Content type may vary {feed} by {feed}

Warning: Some feeds are large. When retrieved from web browser, it may got frozen as browsers are often trying to render the (large) content.

Warning: Target domain uses https protocol and some clients complain about invalid ssl certificate.

Secured by basic

URI Parameters

  • feed: required (string)

    feed identifier in form of text

  • date: required (string - pattern: ^[0-9]{8}$)

    (UTC based) date in format YYYYMMDD

  • version_id: required (string - pattern: ^[0-9]{r}-[0-9a-f]{5}$)

    UTC time based version id with random suffix in format HHMMSS-suffix

HTTP status code 302

Redirection to temporary valid url on another domain for real download.

Body

Type: application/json

Example:

[
    {
        "filename": "cz-DataFusionService-20150625-000019-e64a0.xml", 
        "id": [
            "cz-DataFusionService.xml", 
            "20150625", 
            "000019-e64a0"
        ], 
        "url": "https://flat.dp.ce-traffic.com.s3.amazonaws.com/01fregion/cz/DataFusionService.xml/20150625/000019-e64a0?Signature=6vtt%2FC8tRBSuJxYFhwk84ykmgAA%3D&Expires=1415912131&AWSAccessKeyId=AKIAJBXTB3W6TPH7OEQA"
    }
]

Type: text/plain

Example:

https://flat.dp.ce-traffic.com.s3.amazonaws.com/01fregion/cz/DataFusionService.xml/20150625/000019-e64a0?Signature=YtRjck%2Bl3C2AfIwyqN1A3A9P7Ds%3D&Expires=1415912007&AWSAccessKeyId=AKIAJBXTB3W6TPH7OEQA

Access to versions without knowing exact date and version_id

get

List of versions in given period.

get

List urls of up to 1000 available versions.

List urls of up to 1000 available versions.

Secured by basic

URI Parameters

  • feed: required (string)

    feed identifier in form of text

  • from_time: required (string)

    Start date-time, using simplified date time format (see documentation)

    Example:

    2015-11-14T10:00:00
  • until: (string)

    End of given period expressed by means of simplified date time format (see documentation)

    If empty, the time is calculated as +24 hours after {from_time}

Headers

  • accept: (one of application/json, text/plain)

HTTP status code 200

Body

Type: text/csv

Example:

https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150529/versions/000100-12dc3
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150529/versions/000158-78552
https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150529/versions/000303-9ba9d

Type: aplication/json

Example:

[
  {
      "url": "https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150529/versions/000100-12dc3",
      "id": [
          "20150529",
          "000100-12dc3"
      ]
  },
  {
      "url": "https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150529/versions/000158-78552",
      "id": [
          "20150529",
          "000158-78552"
      ]
  },
  {
      "url": "https://feedhistory.api.ce-traffic.com/0.1dev2/feeds/pl-DataFusionService.xml/days/20150529/versions/000303-9ba9d",
      "id": [
          "20150529",
          "000303-9ba9d"
      ]
  }
]

HTTP status code 204

No content. Feed exists, but no versions for given date-time was found.

HTTP status code 400

Bad Request. Format of from or to is not following expected format.

HTTP status code 404

Feed with given name not found

Content of first feed version in given period.

get

get

Get feed version.

Note: Content type may vary {feed} by {feed}

Warning: Some feeds are large. When retrieved from web browser, it may got frozen as browsers are often trying to render the (large) content.

Warning: Target domain uses https protocol and some clients complain about invalid ssl certificate.

Get feed version.

Note: Content type may vary {feed} by {feed}

Warning: Some feeds are large. When retrieved from web browser, it may got frozen as browsers are often trying to render the (large) content.

Warning: Target domain uses https protocol and some clients complain about invalid ssl certificate.

Secured by basic

URI Parameters

  • feed: required (string)

    feed identifier in form of text

  • from_time: required (string)

    Start date-time using flexible date-time format (see documentation)

    Example:

    2015-11-14T10:00:00

HTTP status code 302

Redirection to temporary valid url on another domain for real download.

Body

Type: application/json

Example:

[
    {
        "filename": "cz-DataFusionService-20150625-000019-e64a0.xml", 
        "id": [
            "cz-DataFusionService.xml", 
            "20150625", 
            "000019-e64a0"
        ], 
        "url": "https://flat.dp.ce-traffic.com.s3.amazonaws.com/01fregion/cz/DataFusionService.xml/20150625/000019-e64a0?Signature=6vtt%2FC8tRBSuJxYFhwk84ykmgAA%3D&Expires=1415912131&AWSAccessKeyId=AKIAJBXTB3W6TPH7OEQA"
    }
]

Type: text/plain

Example:

https://flat.dp.ce-traffic.com.s3.amazonaws.com/01fregion/cz/DataFusionService.xml/20150625/000019-e64a0?Signature=YtRjck%2Bl3C2AfIwyqN1A3A9P7Ds%3D&Expires=1415912007&AWSAccessKeyId=AKIAJBXTB3W6TPH7OEQA

HTTP status code 404

Feed with given name not found or Feed version not found