Tiny Visions API

Tiny Visions API Documentation

About the API

The Tiny Visions API provides access to the Tiny Visions dataset of New Zealand music videos.

  • This API is read-only
  • Requires no authentication
  • Follows the JSON:API v1.0 specification

Base URL

https://tinyvisions.nz/api/v1

Resources

The API offers two primary resources.

Entities

Provides descriptive metadata associated with an individual, group, or other body connected to the existence of a music video.

Videos

Provides descriptive metadata associated with a music video.

Primary resources

/entities
/videos

Single object

{ "data": { "type": "videos", "id": "09ad4078-b1d0-4cc3-808e-e99ed715f877", "attributes": {}, "links": {} } }

Collection object

{ "data": [ { "type": "videos", "id": "09ad4078-b1d0-4cc3-808e-e99ed715f877", "attributes": {}, "links": {} }, { "type": "videos", "id": "0eb2d603-2665-489f-b63e-52c3547cfa58", "attributes": {}, "links": {} } ], "meta": {}, "links": {} }

Parameters

Optional parameters are available for each resource and can be applied to single, collection, and filter requests. Including parameters with a request will return supplemental data for the resource.

Entities & Videos

credits, images, tags, albums

Entities

resources

Videos

streams

Use a parameter

?include=streams

Parameters response

{ "data": { "type": "videos", "id": "09ad4078-b1d0-4cc3-808e-e99ed715f877", "relationships": { "streams": { "data": { "type": "streams", "id": "b223a404-a847-4036-ac8d-a23d57e350ba" } } } }, "included": [ { "type": "streams", "id": "b223a404-a847-4036-ac8d-a23d57e350ba", "attributes": { "sources": [ { "source": "vimeo", "sourceId": null, "isPrimary": 0 }, { "source": "youtube", "sourceId": "CIZQHR6-Ngg", "isPrimary": 1 } ] } } ] }

Nested parameters

Additional parameter-specific data can be accessed using dot notation. This is currently suppported for the following parent parameters:

credits.images

Includes image data for each credits object.

albums.images

Includes image data for each albums object.

Use a nested parameter

/entities?include=albums.image

Filters

Resources can be filtered by passing keywords with a terms parameter.

Filter a resource

/search/entities?terms={term}

Pagination

Collections are returned with pagination and links metadata.

Pagination meta

{ "meta": { "pagination": { "total": 11, "count": 5, "per_page": 5, "current_page": 2, "total_pages": 3 } } }

Pagination links

{ "links": { "self": "http://tinyvisions.nz/search/entities?page=2", "first": "http://tinyvisions.nz/search/entities?page=1", "prev": "http://tinyvisions.nz/search/entities?page=1", "next": "http://tinyvisions.nz/search/entities?page=3", "last": "http://tinyvisions.nz/search/entities?page=3" } }

Errors

Responses

Error responses try to provide some context. A typical error message will return:

  • an HTTP status code
  • a generic error title
  • further detail specific to the error
  • the parameter responsible for the error
  • an application-specific error code

Application error codes

TV001

Generic error

TV002

Bad ID format

TV003

ID does not exist

TV004

Invalid route

TV005

Invalid search route

TV006

Model does not exist

Request an invalid UUID

/videos/1b0bd0a9-b308-4a20-beff-39f

Get an error response

{ "errors": [ { "status": 404, "title": "Not Found", "detail": "The ID does not appear to be a valid UUID.", "parameter": "1b0bd0a9-b308-4a20-beff-39f", "code": "TV002" } ] }

Rate Limit

API requests are currently limited to 30 per minute.

License

You are free to share and adapt material for any purpose. To understand usage rights and terms, see the Creative Commons Attribution 4.0 International License: CC BY 4.0.

Copyright

We respect your intellectual property. Please contact us—seer@tinyvisions.nz—if you believe your work has been used in such a way as to infringe your copyright. Intellectual property rights holders are invited to make contact if, as owner, you believe proper attribution has not been made, to allow for correction or removal of your content.

Contact

Please email seer@tinyvisions.nz for support and general enquiries.