Introduction
The AVIN API is a service that allows automatic access to AVIN’s up-to-date wine information. For service access please contact the email address: info@avin.cc. Below you’ll find the technical information related to these services.
Technical Information
The AVIN API provides a simple RESTful interface with XML and Json formatted responses to use many of AVIN’s website features, including producers, wines, country and wine types. This document provides information to developers on how to integrate with the AVIN API.
Concepts
Authentication
The AVIN API requires a developer key which you can ask us using this email address: info@avin.cc. The key identifies you as a unique entity making calls against the AVIN web service, and is used to track overall call usage. Currently, the available API methods access public information, so there is no additional authentication needed.
Terms of Service
For more information please read the API Terms of Service.
HTTP requests
The AVIN API uses a RESTful calling style that works with standard HTTP GET calls. (Future versions of the AVIN API will use additional HTTP methods.) Any web programming language (PHP, Ruby, Perl, Python, C#, VB, Java…) should be able to make and receive HTTP networking calls; consult the documentation for your language of choice.
Rate limiting
Clients are allowed 1000 requests per day. If your application needs more than the allotted amount of calls, contact us at info@avin.cc with a description of the application and an estimate on call usage. (You might also want to investigate the use of caching to keep the number of calls to a minimum, and make your application more responsive.)
Pagination limiting
The default set of returned records in a call is 100.
Encoding
The AVIN API uses both JSON, a lightweight data serialization language that is compatible with many different languages, and XML a standard inter system serialization language.
How to make a request and process the response
Here’s a step-by-step example of how to make a request to the AVIN API. We’ll make a request to get details for a wine called “Cortes de Cima Reserva 2003″ with an avin = AVIN6452997073019. Using the GetWineByAvin method. If you consult the documentation for that method, you’ll see something like this:
GetWineByAvin
| Method Name |
GetWineByAvin |
| Synopsis |
Gets a wine by Avin. |
| HTTP Method |
GET |
| URI |
/GetWineByAvin/(AVIN){avin_number} |
| Parameters |
| Name |
Required |
Default |
Type |
Key |
Y |
|
string |
avin |
Y |
|
int |
vintage |
N |
|
int |
country |
N |
0 |
int |
type |
N |
0 |
int |
producer |
N |
|
string |
|
| Return Type |
wine list |
Every AVIN API request begins with the base URL: http://api.avin.cc/rest/v1.0 and ends with the URI for the command. Finally, you’ll add a and symbol (“&”) plus any optional parameters you’d like to send (in this case, format), and of course, your API key (a required parameter).
The final request looks like this: http://api.avin.cc/rest/v1.0/GetWineByAvin/AVIN6452997073019/&format=json&key= You can test this right in your browser. You should see a long string of JSON data language. Note that the object returned is of resource type winelist. See section Resource Types for for details on this resource.
Sample request from PHP
Here is an example of a call in a PHP script. You can use any language that supports HTTP requests (JavaScript, Ruby, Perl, C#…) which is just about every language in use on the web.
$url = "http://api.avin.cc/rest/v1.0/GetWineByAvin/AVIN6452997073019/key=";
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response_body = curl_exec($ch);
Sample response>
Here’s the response from our request above (with added white space to make it easier to read.) The response is formatted using JSON, a simple data serialization language that can be used by just about any language on the web. (To find JSON support for your language, go here.)
{ response:{ stat:'OK', aml:{ version:1.0, wines:{ count:1, wine:[ { avin:'AVIN1234567890123', name:'My wine', vintage:2005, type:'White wine', type_id:2, country:'Spain', country_id:724, region:'Catalonia', region_id:72407, producer:'My Producer', producer_id:123, adegga_url:'http:\/\/www.adegga.com\/wine\/ AVIN1234567890123', label_url:{} } ] }, legal:'By using this data you agree to the AVIN API terms of service.' } } }
Notice the strange looking “\/” sequences are a side-effect of the JSON encoding, and will be converted to normal forward slashes when you decode the response data.
Sample Response in PHP
And here’s how we’d parse and use the response in PHP:
$response = json_decode($response_body);
$wine = $response->results[0];
print $wine->name."'s producer is: " . $wine->producer."\n";
Resource Types
Each command in the AVIN API will return objects of one of the following types:
Country list – represent collection of countries.
Winetype list – represents a collection of wine types.
Producer list – represents a collection of producers.
Wine list – represent a collection of wines.
Country list
| Field |
Type |
Description |
id |
int |
The country’s id. |
name |
string |
The country’s name. |
iso |
string |
The country’s 2-letter iso code. |
Winetype list
| Field |
Type |
Description |
id |
int |
The wine type’s id. |
type |
string |
The wine type’s description. |
Producer list
| Field |
Type |
Description |
id |
int |
The wine type’s id. |
name |
string |
The producer’s name. |
long_name |
string |
The producer’s long name. |
country |
string |
The producer’s country name. |
country_id |
int |
The producer’s country id. |
adegga_url |
string |
The producer’s AVIN page url. |
logo_url |
string |
The producer’s logo AVIN url. |
producer_url |
string |
The producer’s website url. |
nr_wines |
int |
The producer’s wine count. |
Wine list
| Field |
Type |
Description |
avin |
string |
The wine’s Avin unique id. |
name |
string |
The wine’s name. |
vintage |
int |
The wine’s vintage. |
type |
string |
The wine’s type name. |
type_id |
int |
The wine’s type id. |
country |
string |
The wine’s country name. |
country_id |
int |
The wine’s country id. |
region |
string |
The wine’s region name. |
region_id |
int |
The wine’s region id. |
producer |
string |
The wine’s producer name. |
producer_id |
int |
The wine’s producer id. |
adegga_url |
string |
Url to Adegga wine page. |
varietals |
string |
The wine’s list of varietals (comma-separated) |
label_url |
string |
Url to label image. |
ratings |
rating list |
list of ratings |
adegga_info |
specific site info |
list of specific site info |
Specific Site Info
| Field |
Type |
Description |
url |
string |
Url to specific site wine page. |
num_notes |
integer |
Number of tasting notes. |
num_favourites |
integer |
Number of people who have favourited wine. |
num_wishlist |
integer |
Number of people who have wine on wishlist. |
Rating list
| Field |
Type |
Description |
adegga |
float |
The adegga rating. |
Methods
GetCountries
| Method Name |
GetCountries |
| Synopsis |
Gets a list of countries you can use for filtering wines and producers. |
| HTTP Method |
GET |
| URI |
/GetCountries |
| Parameters |
| Name |
Required |
Default |
Type |
Key |
Y |
|
string |
|
| Return Type |
country list |
GetWineTypes
| Method Name |
GetWineTypes |
| Synopsis |
Gets a list of wine types you can filter wines and producers |
| HTTP Method |
GET |
| URI |
/GetWineTypes |
| Parameters |
| Name |
Required |
Default |
Type |
Key |
Y |
|
string |
|
| Return Type |
wine type list |
GetProducerByID
| Method Name |
GetProducerByID |
| Synopsis |
Gets a producer by id |
| HTTP Method |
GET |
| URI |
/GetProducerByID/{producer_id} |
| Parameters |
| Name |
Required |
Default |
Type |
Key |
Y |
|
string |
producer_id |
Y |
|
int |
country |
N |
0 |
int |
|
| Return Type |
Producers list |
GetProducersByName
| Method Name |
GetProducersByName |
| Synopsis |
Gets a producer by name. |
| HTTP Method |
GET |
| URI |
/GetProducersByName/{producer_name} |
| Parameters |
| Name |
Required |
Default |
Type |
Key |
Y |
|
string |
producer_name |
Y |
|
string |
country |
N |
0 |
int |
page |
N |
1 |
int |
sortorder |
N |
desc |
asc/desc |
sortby |
N |
name |
name/longname/country |
|
| Return Type |
producers list |
GetWineByAvin
| Method Name |
GetWineByAvin |
| Synopsis |
Gets a wine by Avin. |
| HTTP Method |
GET |
| URI |
/GetWineByAvin/(AVIN){avin_number} |
| Parameters |
| Name |
Required |
Default |
Type |
Key |
Y |
|
string |
avin |
Y |
|
int |
vintage |
N |
|
int |
country |
N |
0 |
int |
type |
N |
0 |
int |
producer |
N |
|
string |
|
| Return Type |
wine list |
GetWinesByName
| Method Name |
GetWinesByName |
| Synopsis |
Gets wine by name |
| HTTP Method |
GET |
| URI |
/GetWinesByName/{name} |
| Parameters |
| Name |
Required |
Default |
Type |
Key |
Y |
|
string |
name |
Y |
|
string |
vintage |
N |
|
int |
country |
N |
0 |
int |
type |
N |
0 |
int |
producer |
N |
|
string |
page |
N |
1 |
int |
sortorder |
N |
desc |
asc/desc |
sortby |
N |
name |
name/vintage/producer/adeggarating |
|
| Return Type |
wine list |
Any questions regarding the API please let us know via email: info@avin.cc
Loading...