Querying the server

To use timetric’s data input/output API, you need to know which series you want to deal with (and thus which URLs to talk to). For example, some things you might want to do:

  • You might want a list of all of the series you own
  • You might want a list of data tagged in a particular way
  • You might want to do an exploratory search of timetric’s data

Relevant URLs

There are two URLs involved in querying nugget lists:

/tag/TAGLIST/
/search/

For any queries involving tagging, the collection of series is available under the first URL; for all other queries, the collection is available under the second.

Query axes

There are three axes along which you can refine your query:

  • Tags
  • String search
  • Username search

Output formats

Search results can be returned in several formats. The default is HTML, but you can also request Atom, as well as two JSON formats (“thick” and “thin”). Selection between the different formats is done by appending results.FORMAT to the path component of the URL.

Thus:

/search/results.atom?u=johndoe

shows details about John Doe’s data, in an Atom format, while:

/tags/cheese/results.thin.json?q=Gorgonzola

shows details about series tagged with cheese, with Gorgonzola in the description, and gives the details in the thin json format.

  • HTML

    HTML results can be viewed in a browser. The structure of the HTML is liable to change, but it will always be usefully viewable in a browser.

  • Atom

    Atom results are given in the Atom/Opensearch format (see http://opensearch.org).

    Example output:

    <feed xmlns="http://www.w3.org/2005/Atom"
  xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>Timetric Search: </title>
  <link href="http://timetric.com/search/results.atom?q=footwear;n=20;p=1"/>
  <updated></updated>
  <author>
    <name>Timetric</name>
  </author>
  <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>
  <opensearch:totalResults>371</opensearch:totalResults>
  <opensearch:startIndex>1</opensearch:startIndex>
  <opensearch:itemsPerPage>20</opensearch:itemsPerPage>
  <opensearch:Query role="request" searchTerms="footwear" count="20" startPage="page.number"/>
  <link rel="alternate"
    href="http://timetric.com/search/?q=footwear;n=20;p=1"
    type="text/html"/>
  <link rel="self"
    href="http://timetric.com/search/results.atom?q=footwear;n=20;p=1"
    type="application/atom+xml"/>
  <link rel="first"
    href="http://timetric.com/search/results.atom?q=footwear;n=20;p=1"
    type="application/atom+xml"/>
  <link rel="next"
    href="http://timetric.com/search/results.atom?q=footwear;n=20;p=2"
    type="application/atom+xml"/>
  <link rel="last"
    href="http://timetric.com/search/results.atom?q=footwear;n=20;p=19"
    type="application/atom+xml"/>
  <link rel="search"
    href="http://timetric.com/opensearch.xml"
    type="application/opensearchdescription+xml"/>

    <!-- results -->

</feed>

    and each result will look something like:

    <entry>
 <title>03.2.2 Footwear Repair and hire of footwear CP SA : yearly</title>
 <link href="http://timetric.com/series/_1H7WjD9RKS0-W3qOzOqIw/"/>
 <id>tag:http://timetric.com,2009-06-23:SearchResults:_1H7WjD9RKS0-W3qOzOqIw</id>
 <updated>2009-07-06T13:00:17</updated>
 <content type="text">
  Crown copyright. Source: National Statistics website:www.statistics.gov.uk.
  Crown copyright material is reproduced with the permission of the Controller
  Office of Public Sector Information (OPSI).
  (from http://www.statistics.gov.uk/statbase/tsdlistfiles.asp)
 </content>
</entry>

  • JSON

    JSON results are closely modelled after the opensearch format; a dictionary is returned, giving both pagination details (with names identical to those in the opensearch spec) and results. Typical JSON output would look like:

    {"totalResults": 371,
 "startIndex": 1,
 "itemsPerPage": 20,
 "links":{
   "self": "http://timetric.com/search/results.thin.json?q=footwear&p=1&n=20",
   "first": "http://timetric.com/search/results.thin.json?q=footwear&p=1&n=20",
   "previous": null,
   "next": "http://timetric.com/search/results.thin.json?q=footwear&p=2&n=20",
   "last":"http://timetric.com/search/results.thin.json?q=footwear&p=19&n=20"
 },
 "results": [ /* list of search results */ ]
}

    while the series details appear in the results list:

    • Thin JSON

      In thin JSON, the details given for each series consist only of its id and URL:

      { /* pagination */
 "results":
   [
     {"name": "adR4JS_USY2ljLZPehLbKQ",
      "url": "http://timetric.com/series/adR4JS_USY2ljLZPehLbKQ/"},
    /* more results */
   ]
}

    • Thick JSON

      In thick json, the details given for each series include those for thin JSON, and also:

      • title
      • caption
      • description
      • units
      • origin
      • license

      Example output:

      { /* pagination */
 "results":
   [
     {"name": "adR4JS_USY2ljLZPehLbKQ",
     "title": "03.2.1 Footwear",
      "caption": "03.2.1 Footwear Shoes and other footwear IDEF NSA 2003=100 : quarterly",
      "description": "03.2.1 Footwear Shoes and other footwear IDEF NSA 2003=100 : quarterly",
      "units": "GBP/100",
      "origin": "UK Office of National Statistics,
                 http://www.statistics.gov.uk/statbase/tsdlistfiles.asp",
      "license": "Crown copyright. Source: National Statistics website: www.statistics.gov.uk.
                  Crown copyright material is reproduced with the permission of the Controller
                  Office of Public Sector Information (OPSI).",
      "url": "http://timetric.com/series/adR4JS_USY2ljLZPehLbKQ/"},
    /* more results */
   ]
}
Timetric Network
About Us
Support
Other