Query API documentation

Usage Examples

A YouTube item

http://uriplay.org/doc.rdf.xml?uri=http%3A//www.youtube.com/watch%3Fv%3DpliAz4L-sAQ

A podcast

http://uriplay.org/doc.rdf.xml?uri=http%3A//downloads.bbc.co.uk/podcasts/radio4/today/rss.xml

A list of podcasts, as an RSS feed

http://uriplay.org/list.rss?uri=http%3A//uriplay.org/download/samples/itunes-example.opml

A Wikpedia item

http://uriplay.org/list.rss?uri=http%3A//en.wikipedia.org/wiki/The_West_Wing

Items involving a person, as an RSS feed

http://uriplay.org/list.rss?uri=http%3A//en.wikipedia.org/wiki/Aaron_Sorkin

A list of items mentioned in the Twitter search for 'funny':

http://uriplay.org/doc.rdf.xml?uri=http%3A//search.twitter.com/search.atom%3Fq%3Dfunny

Synopsis

http://uriplay.org/<graph>[.<format>]?uri=<resource>[&profile=<profile>]

Description

A URIplay endpoint allows clients to query metadata for playable resources using any known name (URI) for the resource. Clients may choose to have their results formatted in a variety of serialisations (eg. JSON, RDF, ATOM, RSS). They may also specify, to a limited extent, which related resources they would like included in the results.

URIplay enpoints intend to make four types of information accessible to clients:

  1. Human readable data intended to allow clients to present a simple description of the resource in their user interface (eg. dc:title, dc:description, etc).
  2. Media focused metadata intended to allow clients to determine how to locate and play a given resource, and, where alternatives exist, choose the most appropriate way to access a resource.
  3. Alternate and common names for a resource, any of which may be used to identify the resource in a query.
  4. Taxonomies and various creative relationships (creator, cast member, producer, etc) presented as simple collections of resources - intended to make these relationships accessible to players without passing on the burden of interpretation.

To satisfy a clients query, the URIplay endpoint will query a number of known, common sources of metadata, and will also apply a set of simple rules - for example, is the resource URI retrievable via a known protocol and does it return metadata that we understand. It then aggregates, and possibly caches, the known metadata for a given resource and returns it in the serialization requested.

Note: Some metadata may be discarded if it cannot be included in the serialisation requested.

In more formal terms, a URIplay endpoint, returns both a set of attributes for the requested resource name and a graph of resources that are related to it.

The URIplay query API responds only to HTTP GET requests.

Parameters

resource

Specifies the name (URI) of the resource being queried. The URI may be any name by which the resource is known.
graph

Select one from a set of predefined criteria, restricting the related resources that should be included in the returned graph, according to the type of the connecting relationship. The graph parameter may take the following values:

doc

The following relations are resolved and included in the returned graph:

  • dcterms:hasPart
  • po:version
  • play:manifestedAs
  • play:availableAt

All other relations are included as unresolved references.
item

The requested resource is required to be of type play:Item.

The following relations are resolved and included in the returned graph:

  • po:version
  • play:manifestedAs
  • play:availableAt

All other relations are included as unresolved references.
list

The requested resource is required to be of type play:List.

The following relations are resolved and included in the returned graph:

  • dcterms:hasPart
  • po:version
  • play:manifestedAs
  • play:availableAt

Additionally, dcterms:hasPart is resolved transitively so that the requested resource declares a direct relationship to all of its decendents.

All other relations are included as unresolved references.
lists

The requested resource is required to be of type play:List.

The following relations are resolved and included in the returned graph:

  • dcterms:hasPart
  • po:version
  • play:manifestedAs
  • play:availableAt

All other relations are included as unresolved references.
format

Specifies the serialisation format of the result. The format parameter may take the following values:

.rdf.xml application/rdf+xml
.rdf.json application/x-json
.atom application/atom+xml
.rss application/rss+xml

If unspecified, user agents may specify a preference through an 'Accept' HTTP header.

Default value: application/rdf+xml
profile

Select one from a set of predefined criteria, restricting the resources that should be included in the returned graph, according to the values of their attributes. The profiles typically restrict resources to property ranges required by particular devices. The profile parameter may take the following values:

all Does not restrict the returned resources.
playable Restricts return resources to only those that transitively contain a play:Location via play:availableAt.
worldwide

Restricts return resources to only those that transitively contain a play:Location via play:availableAt.
play:Locations are restricted to ?x for the following statements:

  • ?x play:restrictedBy ?y . FILTER (?y != <http://open.bbc.co.uk/rad/uriplay/policy/7days-uk-only>)
embed

Restricts return resources to only those that transitively contain a play:Location via play:availableAt.
play:Locations are restricted to ?x for the following statements:

  • ?x play:transportType 'embedobject'
download

Restricts return resources to only those that transitively contain a play:Location via play:availableAt.
play:Locations are restricted to ?x for the following statements:

  • ?x play:transportType 'download'
iphone

Restricts return resources to only those that transitively contain a play:Location via play:availableAt.
play:Locations are restricted to ?x for the following statements:

  • ?x play:transportType 'download'
  • ?x play:transportSubType 'HTTP'

play:Encodings are restricted to ?y for the following statements:

  • OPTIONAL { { ?y play:dataContainerFormat 'audio/mp4' }
    UNION
    { ?y play:dataContainerFormat 'video/mp4' }
    UNION
    { ?y play:dataContainerFormat 'audio/mpeg' }
    UNION
    { ?y play:dataContainerFormat 'video/quicktime' } }
  • OPTIONAL { { ?y play:videoCoding 'video/H263' }
    UNION
    { ?y play:videoCoding 'video/H264' } }
  • OPTIONAL { { ?y play:audioCoding 'audio/mp4' }
    UNION
    { ?y play:audioCoding 'audio/mpeg' } }
  • OPTIONAL { { ?y play:videoBitRate ?a } . FILTER (?a <= 2460) }
  • OPTIONAL { { ?y play:audioBitRate ?b } . FILTER (?b <= 160) }
  • OPTIONAL { { ?y play:videoFrameRate ?c } . FILTER (?c <= 30) }
  • OPTIONAL { { ?y play:videoHorizontalSize ?d } . FILTER (?d <= 640) }
  • OPTIONAL { { ?y play:videoVerticalSize ?e } . FILTER (?e <= 480) }
web

Restricts return resources to only those that transitively contain a play:Location via play:availableAt.
play:Locations are restricted to ?x for the following statements:

  • ?x play:transportType 'htmlembed'

Default value: all

Prefixes

This documentations uses the following prefixes to refer to the corresponding namespaces:

playhttp://uriplay.org/elements/
pohttp://purl.org/ontology/po/
dctermshttp://purl.org/dc/terms/

Usage Examples

Retrieve resources from the Twitter search for YouTube.com:

http://uriplay.org/doc.rdf.xml?uri=http%3A//search.twitter.com/search.atom%3Fq%3DYouTube.com

Error Codes

404Unable to retrieve source document.
406Unable to format the resulting graph in the serialisation requested.