Porto Wine Market 2014 | Porto | 5 de Abril
Prove os melhores vinhos de 30 produtores seleccionados.

Home > Help

Adegga API

Introduction

The Adegga API provides a simple RESTful interface with XML and Json formatted responses to use many of Adegga’s website features, including producers, wines, country and wine types. This document provides information to developers on how to integrate with the Adegga API.

Concepts

Authentication
The Adegga API requires a developer key which you can ask us using this request form. The key identifies you as a unique entity making calls against the Adegga 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 Adegga API uses a RESTful calling style that works with standard HTTP GET calls. (Future versions of the Adegga 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 dev@adegga.com 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 Adegga 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 Adegga 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 Adegga API request begins with the base URL: http://api.adegga.com/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.adegga.com/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.adegga.com/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 Adegga 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 Adegga 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 adegga page url.
logo_url string The producer’s logo adegga 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.
varietals string The wine’s list of varietals (comma-separated)
adegga_url string Url to adegga wine page.
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.

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

This entry was posted in API and tagged . Bookmark the permalink.