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).
| Value | Real meaning |
|---|---|
2015 | invalid |
2015-11 | invalid |
2015-11-1 | invalid |
2015-11-14 | 2015-11-14T00:00:00Z |
2015-11-14T10 | 2015-11-14T10:00:00Z |
2015-11-14T10:5 | 2015-11-14T10:50:00Z |
2015-11-14T10:05:06 | 2015-11-14T10:05:06Z |
2015111410 | 2015-11-14T10:00:00Z |
20151114105 | 2015-11-14T10:50:00Z |
2015-11-14T1005 | 2015-11-14T10:05:00Z |
2015-11-14T100506 | 2015-11-14T10:05:06Z |
/feeds
Days for which given feed has some versions
List days for which exist some feed versions
time based version identifiers of available feed versions
List feed versions for given date
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.
Access to versions without knowing exact date and version_id
List of versions in given period.
List urls of up to 1000 available versions.
Content of first feed version in given period.
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.