API documentation

Introduction

This is our API and it's ~~a ripoff of~~ very similar to last.fm's.

Get an API key

To use our webservice you need an API key, to get one contact us who you are and why you want an API key. Once we approve you we'll send you a md5 hash you can use. Each key comes by default with a 1500 requests/hour limit.

Overview

Our API is purely RESTful with each request needing a api_key, a method, and a extra parameter that depends on the method chosen. The response format is XML by default, although this can be overriden using the format parameter to ask for the response to be in json.

Example request URL

http://www.nvivo.es/api/request.php?api_key=XXX&method=user.getEvents&user=hermzz&format=json

Any request will return at least some XML or JSON, the status indicates whether the request was valid or if there was a problem. See the appendix for a list of error IDs and what they mean.

Example succesful XML response

<?xml version="1.0" encoding="UTF-8" ?>
<response status="success" xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos">
<events>
[ ... ]
</events>
</response>

Example failed JSON response

{"status": "error", "error": {"id": 7, "message": "The artist you requested doesn\'t exist"}}

API Methods

user

user.getEvents

Returns the events a user will be going to.

Required parameters

user: The username of the user

Optional parameters

past: Returns gigs in the past when set to "true"

Example request

?api_key=XXX&method=user.getEvents&user=gafeman

Example response

<?xml version="1.0" encoding="UTF-8" ?>
<response status="success" xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos">
<events>
<event>
<id>16004</id>
<name><![CDATA[The Wombats]]></name>
<artists>
<artist url="http://www.nvivo.es/artistas/n/The+Wombats/"><![CDATA[The Wombats]]></artist>
</artists>
<venue>
<id>91</id>
<name><![CDATA[Sala Heineken]]></name>
<location>
<city>Madrid</city>
<country>España</country>
<street>Princesa, 1</street>
<postalcode></postalcode>
<geo:point>
<geo:lat>40.4246</geo:lat>
<geo:long>-3.71199</geo:long>
</geo:point>
</location>
<url>http://www.nvivo.es/salas/i/91/</url>
</venue>
<tickets_url>http://www.nvivo.es/entradas-The+Wombats-Madrid-16004.html</tickets_url>
<startDate>2008-11-04 20:00:00</startDate>
<modDate>2008-08-26 12:25:18</modDate>
<description><![CDATA[Entrada General: 18€ en ticktackticket.com]]></description>
<image size="small">http://d3a4xefn3j5zbg.cloudfront.net/carteles/43x43/v2_43_thumb_portada_11.jpg</image>
<image size="medium">http://d3a4xefn3j5zbg.cloudfront.net/carteles/80x80/v2_80_thumb_portada_11.jpg</image>
<image size="large">http://d3a4xefn3j5zbg.cloudfront.net/carteles/239xY/v2_239xY_thumb_portada_11.jpg</image>
<attendance>3</attendance>
<tag>fivegig:gig=16004</tag>
<url>http://www.nvivo.es/conciertos/i/16004/</url>
</event>

[ ... ]

</events>
</response>

venue

venue.get

Returns the basic information of a venue

Required parameters

venue_id: The venue ID

Example request

?api_key=XXX&method=venue.get&venue_id=91

Example response

<?xml version="1.0" encoding="UTF-8" ?>
<response status="success" xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos">
<venue>
<id>91</id>
<name><![CDATA[Sala Heineken]]></name>
<location>
<city>Madrid</city>
<country>España</country>
<street>Princesa, 1</street>
<postalcode></postalcode>
<geo:point>
<geo:lat>40.4246</geo:lat>
<geo:long>-3.71199</geo:long>
</geo:point>
</location>
<url>http://www.nvivo.es/salas/i/91/</url>
</venue>
</response>

venue.find

Searches for a venue by name

Required parameters

venue_name: The venue name

Optional parameters

country_iso: Filter by country ISO code (use 'all' parameter to skip country filter)

Example request

?api_key=XXX&method=venue.find&venue_name=sala+heineken

Example response

<?xml version="1.0" encoding="UTF-8" ?>
<response status="success" xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos">
<venues>
<venue>
<id>91</id>
<name><![CDATA[Sala Heineken]]></name>
<location>
<city>Madrid</city>
<country>España</country>
<street>Princesa, 1</street>
<postalcode></postalcode>
<geo:point>
<geo:lat>40.4246</geo:lat>
<geo:long>-3.71199</geo:long>
</geo:point>
</location>
<url>http://www.nvivo.es/salas/i/91/</url>
</venue>
</venues>
</response>

venue.getEvents

Returns the gigs that will be happening at a specific venue.

Required parameters

venue_id: The venue ID

Optional parameters

past: Returns gigs in the past when set to "true"

Example request

?api_key=XXX&method=venue.getEvents&venue_id=91

Example response

<?xml version="1.0" encoding="UTF-8" ?>
<response status="success" xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos">
<events>
<event>
<id>15683</id>
<name><![CDATA[A.Vega y J.M.Granados en Madrid]]></name>
<artists>
<artist url="http://www.nvivo.es/artistas/n/Jose+Mar%C3%ADa+Granados/"><![CDATA[Jose María Granados]]></artist>
<artist url="http://www.nvivo.es/artistas/n/Antonio+Vega/"><![CDATA[Antonio Vega]]></artist>
</artists>
<tickets_url>http://www.nvivo.es/entradas-Jose+Mar%C3%ADa+Granados+Antonio+Vega-Madrid-15683.html</tickets_url>
<startDate>2008-11-04 20:00:00</startDate>
<modDate>2008-08-26 12:25:18</modDate>
<description><![CDATA[Proximo concierto de Antonio Vega y Jose Maria Granados en la sala Heineken de Madrid, el 9-10-2008.

Entradas a la venta en
http://www.ticktackticket.com/entradas/goto. do?evento=Antonio+Vega+%2B+Jose+M%AA+Granados+%2F+Mama&poblacion=

Entrada General: 22,00 Euros (+ gastos servicio venta anticipada)]]></description>
<image size="small">http://d3a4xefn3j5zbg.cloudfront.net/carteles/43x43/v2_43_thumb_portada_11.jpg</image>
<image size="medium">http://d3a4xefn3j5zbg.cloudfront.net/carteles/80x80/v2_80_thumb_portada_11.jpg</image>
<image size="large">http://d3a4xefn3j5zbg.cloudfront.net/carteles/239xY/v2_239xY_thumb_portada_11.jpg</image>
<attendance>3</attendance>
<tag>fivegig:gig=15683</tag>
<url>http://www.nvivo.es/conciertos/i/15683/</url>
</event>

[ ... ]

</events>
</response>

city

city.getEvents

Returns the gigs that will be happening at a specific city.

Required parameters

city: The name of the city

Optional parameters

country_iso: Filter by country ISO code (use 'all' parameter to skip country filter)
past: Returns gigs in the past when set to "true"

Example request

?api_key=XXX&method=city.getEvents&city=Madrid

Example response

<?xml version="1.0" encoding="UTF-8" ?>
<response status="success" xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos">
<events>
<event>
<id>15683</id>
<name><![CDATA[A.Vega y J.M.Granados en Madrid]]></name>
<artists>
<artist url="http://www.nvivo.es/artistas/n/Jose+Mar%C3%ADa+Granados/"><![CDATA[Jose María Granados]]></artist>
<artist url="http://www.nvivo.es/artistas/n/Antonio+Vega/"><![CDATA[Antonio Vega]]></artist>
</artists>
<venue>
<id>91</id>
<name><![CDATA[Sala Heineken]]></name>
<location>
<city>Madrid</city>
<country>España</country>
<street>Princesa, 1</street>
<postalcode></postalcode>
<geo:point>
<geo:lat>40.4246</geo:lat>
<geo:long>-3.71199</geo:long>
</geo:point>
</location>
<url>http://www.nvivo.es/salas/i/91/</url>
</venue>
<tickets_url>http://www.nvivo.es/entradas-Jose+Mar%C3%ADa+Granados+Antonio+Vega-Madrid-15683.html</tickets_url>
<startDate>2008-11-04 20:00:00</startDate>
<modDate>2008-08-26 12:25:18</modDate>
<description><![CDATA[Proximo concierto de Antonio Vega y Jose Maria Granados en la sala Heineken de Madrid, el 9-10-2008.

Entradas a la venta en
http://www.ticktackticket.com/entradas/goto. do?evento=Antonio+Vega+%2B+Jose+M%AA+Granados+%2F+Mama&poblacion=

Entrada General: 22,00 Euros (+ gastos servicio venta anticipada)]]></description>
<image size="small">http://d3a4xefn3j5zbg.cloudfront.net/carteles/43x43/v2_43_thumb_portada_11.jpg</image>
<image size="medium">http://d3a4xefn3j5zbg.cloudfront.net/carteles/80x80/v2_80_thumb_portada_11.jpg</image>
<image size="large">http://d3a4xefn3j5zbg.cloudfront.net/carteles/239xY/v2_239xY_thumb_portada_11.jpg</image>
<attendance>3</attendance>
<tag>fivegig:gig=15683</tag>
<url>http://www.nvivo.es/conciertos/i/15683/</url>
</event>

[ ... ]

</events>
</response>

artist

artist.getEvents

Returns the gigs an artist will be playing at.

Required parameters

artist: The name of the artist

Optional parameters

country_iso: Filter by country ISO code (use 'all' parameter to skip country filter)
past: Returns gigs in the past when set to "true"

Example request

?api_key=XXX&method=artist.getEvents&artist=Sigur+Rós

Example response

<?xml version="1.0" encoding="UTF-8" ?>
<response status="success" xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos">
<events>
<event>
<id>18531</id>
<name><![CDATA[Sigur Rós]]></name>
<artists>
<artist url="http://www.nvivo.es/artistas/n/Sigur+R%C3%B3s/"><![CDATA[Sigur Rós]]></artist>
</artists>
<venue>
<id>4073</id>
<name><![CDATA[Wolverhampton Civic Hall]]></name>
<location>
<city>Wolverhampton</city>
<country>Great Britain</country>
<street>North Street</street>
<postalcode>WV1 1</postalcode>
<geo:point>
<geo:lat></geo:lat>
<geo:long></geo:long>
</geo:point>
</location>
<url>http://www.nvivo.es/salas/i/4073/</url>
</venue>
<tickets_url>http://www.nvivo.es/entradas-Jose+Mar%C3%ADa+Granados+Antonio+Vega-Madrid-15683.html</tickets_url>
<startDate>2008-11-04 20:00:00</startDate>
<modDate>2008-08-26 12:25:18</modDate>
<description><![CDATA[£5 - £23]]></description>
<image size="small">http://d3a4xefn3j5zbg.cloudfront.net/carteles/43x43/v2_43_thumb_portada_11.jpg</image>
<image size="medium">http://d3a4xefn3j5zbg.cloudfront.net/carteles/80x80/v2_80_thumb_portada_11.jpg</image>
<image size="large">http://d3a4xefn3j5zbg.cloudfront.net/carteles/239xY/v2_239xY_thumb_portada_11.jpg</image>
<attendance>0</attendance>
<tag>fivegig:gig=18531</tag>
<url>http://www.nvivo.es/conciertos/i/18531/</url>
</event>

[ ... ]

</events>
</response>

Libraries

Appendix

Error IDs

1: Invalid or unexistent API key.
2: API key is over the quota limit.
3: Request is missing parameters, like making a user.getEvents request without specifying a user.
4: Unknown user.
5: Unknown venue.
6: Unknown city.
7: Unknown artist.