GlobalWineScore API Documentation
The GlobalWineScore API is designed as a RESTful API, providing several resources and methods depending on your usage plan
COMMUNITYAPI KEY0 INSTALLS
OpenAPI Specificationv3.0
{
"openapi": "3.0.0",
"servers": [
{
"url": "https://api.globalwinescore.com"
}
],
"info": {
"contact": {
"x-twitter": "GlobalWineScore"
},
"description": "\n\nThe GlobalWineScore API is designed as a RESTful API, providing several resources and methods depending on your usage plan.\n\nFor further information please refer to <a href=\"https://www.globalwinescore.com/plans\" target=\"_blank\">our plans</a>.\n\n# Authentication\nThe API uses token-based authentication.\nIn order to authenticate your requests, you need to include a specific header in each of your requests:\n\n```\nAuthorization: Token {YOUR-API-TOKEN}\n```\nThe word <b>Token</b> must be written. Your requests must also use the <b>HTTPS</b> protocol.\n\nIf you don't have a token yet, you need to apply for one [here](https://www.globalwinescore.com/api/).\n\nYour personal token can be found under the <a href=\"https://www.globalwinescore.com/account/api/\" target=\"_blank\">My account > API</a> section of the GlobalWineScore website\n\n# Format\nThe API provides several rendering formats which you can control using the `Accept` header or `format` query parameter.\n\n- JSON (default): no header or `Accept: application/json`\n- XML: `Accept: application/xml`\n# Rate limiting\nFor API requests, the rate limit allows for up to 10 requests per minute.\n\n# Error handling\n\nWhether a request succeeded is indicated by the HTTP status code. A 2xx status code indicates success, whereas a 4xx status code indicates failure.\n\nWhen a request fails, the response body is still JSON, but always contains a `detail` field with a description of the error, which you can inspect for debugging.\n\nFor example, trying to access the API without proper authentication will return code 403 along with the message:\n\n`{\"detail\": \"Authentication credentials were not provided.\"}`\n\nFound a bug ? send us an email at <a href=\"mailto:api@globalwinescore.com\">api@globalwinescore.com</a>\n\n# Ordering\n\nAt the moment, GlobalWineScores may be sorted by `date` and `score`. Use \"-\"\nto sort in descending order.\n\n# Continuous synchronization\n\nIf you need to synchronize your database with our API, you can query our API using `?ordering=-date` to get the newest scores first, which means you won't have to crawl the whole catalog every time :-)\n\n# Quick search interface\nIf you need to search our catalog (e.g. to align it with yours), we're providing you with a handy interface accessible here: <a href=\"https://api.globalwinescore.com/search/\" target=\"_blank\">https://api.globalwinescore.com/search/</a>\n\nYou need to be logged in (email/password) to access this page, but other than that you can share it with anyone in your team and start searching right away !\n\n# Resources\n\nThe details about available endpoints can be found below.\nYou can click on each endpoint to find information about their parameters.\n",
"title": "GlobalWineScore API Documentation",
"version": "8234aab51481d37a30757d925b7f4221a659427e",
"x-apisguru-categories": [
"open_data"
],
"x-logo": {
"url": "https://api.apis.guru/v2/cache/logo/https_twitter.com_GlobalWineScore_profile_image.jpeg"
},
"x-origin": [
{
"format": "openapi",
"url": "https://globalwinescore.docs.apiary.io/api-description-document",
"version": "3.0"
}
],
"x-providerName": "globalwinescore.com"
},
"security": [
{
"TokenAuthentication": []
}
],
"paths": {
"/globalwinescores/": {
"description": "https://api.globalwinescore.com/globalwinescores/\n<br/> <b>Require business plan</b> <br/>\nGlobalWineScores are re-computed every time a renotation is published, hence resulting in a score evolution over time.\n\nThis API allows you to retrieve the history of all GlobalWineScores.\n",
"get": {
"description": "Returns all available GWS",
"operationId": "listHistoricalGWS",
"parameters": [
{
"description": "",
"example": "Token <YOUR-API-TOKEN>",
"in": "header",
"name": "Authorization",
"schema": {
"type": "string"
}
},
{
"description": "The exact `id` of the wine. Can be used multiple times (e.g `?wine_id=114959&wine_id=114952`) <br/> If you need to find the `wine_id` for your wines, use our <a href=\"https://api.globalwinescore.com/search/\" target=\"_blank\">search page</a>\n",
"example": [
114959,
114952
],
"explode": true,
"in": "query",
"name": "wine_id",
"schema": {
"items": {
"type": "integer"
},
"type": "array"
}
},
{
"description": "The vintage you want to search against.",
"example": "2000",
"in": "query",
"name": "vintage",
"schema": {
"type": "string"
}
},
{
"description": "The lowercase color of the wine.",
"in": "query",
"name": "color",
"schema": {
"enum": [
"red",
"white",
"pink"
],
"type": "string"
}
},
{
"description": "Only show the <a href=\"See https://en.wikipedia.org/wiki/En_primeur\">en primeur</a> GlobalWineScores\n",
"in": "query",
"name": "is_primeurs",
"schema": {
"default": false,
"type": "boolean"
}
},
{
"description": "L-WIN wine identifier (See definition <a href=\"https://www.liv-ex.com/lwin/\" target=\"_blank\">here</a>)\n",
"example": "1014033",
"in": "query",
"name": "lwin",
"schema": {
"type": "string"
}
},
{
"description": "L-WIN wine/vintage identifier (See definition <a href=\"https://www.liv-ex.com/lwin/\" target=\"_blank\">here</a>)\n",
"example": "10140332000",
"in": "query",
"name": "lwin_11",
"schema": {
"type": "string"
}
},
{
"description": "Number of results to return per page.",
"in": "query",
"name": "limit",
"schema": {
"default": 100,
"minimum": 0,
"type": "integer"
}
},
{
"description": "The initial index from which to return the results.",
"example": 100,
"in": "query",
"name": "offset",
"schema": {
"minimum": 0,
"type": "integer"
}
},
{
"description": "Which field to use when ordering the results.",
"in": "query",
"name": "ordering",
"schema": {
"default": "-date",
"enum": [
"date",
"-date",
"score",
"-score"
],
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"response": {
"value": "{\n \"count\": 1,\n \"next\": null,\n \"previous\": null,\n \"results\": [\n {\n \"wine\": \"Petrus, Pomerol\",\n \"wine_id\": 114959,\n \"wine_slug\": \"petrus-pomerol\",\n \"appellation\": \"Pomerol\",\n \"appellation_slug\": \"pomerol\",\n \"color\": \"Red\",\n \"wine_type\": \"\",\n \"regions\": [\n \"Bordeaux\"\n ],\n \"country\": \"France\",\n \"classification\": null,\n \"vintage\": \"2000\",\n \"date\": \"2016-05-12\",\n \"is_primeurs\": false,\n \"score\": 99.02,\n \"confidence_index\": \"A+\",\n \"journalist_count\": 6,\n \"lwin\": 1014033,\n \"lwin_11\": 10140332000\n }\n ]\n}\n"
}
}
},
"application/xml": {
"examples": {
"response": {
"value": "<root>\n <count>1</count>\n <next/>\n <previous/>\n <results>\n <list-item>\n <wine>Petrus, Pomerol</wine>\n <wine_id>114959</wine_id>\n <wine_slug>petrus-pomerol</wine_slug>\n <appellation>Pomerol</appellation>\n <appellation_slug>pomerol</appellation_slug>\n <color>Red</color>\n <wine_type/>\n <regions>\n <list-item>Bordeaux</list-item>\n </regions>\n <country>France</country>\n <classification/>\n <vintage>2000</vintage>\n <date>2016-05-12</date>\n <is_primeurs>False</is_primeurs>\n <score>99.02</score>\n <confidence_index>A+</confidence_index>\n <journalist_count>6</journalist_count>\n <lwin>1014033</lwin>\n <lwin_11>10140332000</lwin_11>\n </list-item>\n </results>\n</root>\n"
}
}
}
},
"description": ""
}
},
"summary": "List all historical GWS",
"tags": [
"GlobalWineScore"
]
},
"summary": "Historical GWS"
},
"/globalwinescores/latest/": {
"description": "https://api.globalwinescore.com/globalwinescores/latest/",
"get": {
"description": "Returns the latest GWS available per wine/vintage.",
"parameters": [
{
"description": "",
"example": "Token <YOUR-API-TOKEN>",
"in": "header",
"name": "Authorization",
"schema": {
"type": "string"
}
},
{
"description": "The exact `id` of the wine. Can be used multiple times (e.g `?wine_id=114959&wine_id=114952`) <br/> If you need to find the `wine_id` for your wines, use our <a href=\"https://api.globalwinescore.com/search/\" target=\"_blank\">search page</a>\n",
"example": [
114959,
114952
],
"explode": true,
"in": "query",
"name": "wine_id",
"schema": {
"items": {
"type": "integer"
},
"type": "array"
}
},
{
"description": "The vintage you want to search against.",
"example": "2000",
"in": "query",
"name": "vintage",
"schema": {
"type": "string"
}
},
{
"description": "The lowercase color of the wine.",
"in": "query",
"name": "color",
"schema": {
"enum": [
"red",
"white",
"pink"
],
"type": "string"
}
},
{
"description": "Only show the <a href=\"See https://en.wikipedia.org/wiki/En_primeur\">en primeur</a> GlobalWineScores\n",
"in": "query",
"name": "is_primeurs",
"schema": {
"default": false,
"type": "boolean"
}
},
{
"description": "L-WIN wine identifier (See definition <a href=\"https://www.liv-ex.com/lwin/\" target=\"_blank\">here</a>)\n",
"example": "1014033",
"in": "query",
"name": "lwin",
"schema": {
"type": "string"
}
},
{
"description": "L-WIN wine/vintage identifier (See definition <a href=\"https://www.liv-ex.com/lwin/\" target=\"_blank\">here</a>)\n",
"example": "10140332000",
"in": "query",
"name": "lwin_11",
"schema": {
"type": "string"
}
},
{
"description": "Number of results to return per page.",
"in": "query",
"name": "limit",
"schema": {
"default": 100,
"minimum": 0,
"type": "integer"
}
},
{
"description": "The initial index from which to return the results.",
"example": 100,
"in": "query",
"name": "offset",
"schema": {
"minimum": 0,
"type": "integer"
}
},
{
"description": "Which field to use when ordering the results.",
"in": "query",
"name": "ordering",
"schema": {
"default": "-date",
"enum": [
"date",
"-date",
"score",
"-score"
],
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"response": {
"value": "{\n \"count\": 1,\n \"next\": null,\n \"previous\": null,\n \"results\": [\n {\n \"wine\": \"Petrus, Pomerol\",\n \"wine_id\": 114959,\n \"wine_slug\": \"petrus-pomerol\",\n \"appellation\": \"Pomerol\",\n \"appellation_slug\": \"pomerol\",\n \"color\": \"Red\",\n \"wine_type\": \"\",\n \"regions\": [\n \"Bordeaux\"\n ],\n \"country\": \"France\",\n \"classification\": null,\n \"vintage\": \"2000\",\n \"date\": \"2016-05-12\",\n \"is_primeurs\": false,\n \"score\": 99.02,\n \"confidence_index\": \"A+\",\n \"journalist_count\": 6,\n \"lwin\": 1014033,\n \"lwin_11\": 10140332000\n }\n ]\n}\n"
}
}
},
"application/xml": {
"examples": {
"response": {
"value": "<root>\n <count>1</count>\n <next/>\n <previous/>\n <results>\n <list-item>\n <wine>Petrus, Pomerol</wine>\n <wine_id>114959</wine_id>\n <wine_slug>petrus-pomerol</wine_slug>\n <appellation>Pomerol</appellation>\n <appellation_slug>pomerol</appellation_slug>\n <color>Red</color>\n <wine_type/>\n <regions>\n <list-item>Bordeaux</list-item>\n </regions>\n <country>France</country>\n <classification/>\n <vintage>2000</vintage>\n <date>2016-05-12</date>\n <is_primeurs>False</is_primeurs>\n <score>99.02</score>\n <confidence_index>A+</confidence_index>\n <journalist_count>6</journalist_count>\n <lwin>1014033</lwin>\n <lwin_11>10140332000</lwin_11>\n </list-item>\n </results>\n</root>\n"
}
}
}
},
"description": ""
}
},
"summary": "List all latest GWS",
"tags": [
"GlobalWineScore"
]
},
"summary": "GWS"
}
},
"components": {
"securitySchemes": {
"TokenAuthentication": {
"description": "See Authentication section above",
"in": "header",
"name": "Authorization",
"type": "apiKey"
}
}
}
}