GetCatalogueFull

Retrieve the complete product catalogue hierarchy of an owner, including the publication status of each catalogue entry.

This endpoint returns the catalogue structure together with a condensed representation of the wines and their individual vintage records.

It can be used to import or synchronize a vin.co catalogue into a website, an e-commerce platform, a PIM, an ERP or another third-party application.

Unlike GetCatalogueByVincod, which is mainly intended to retrieve the catalogue tree for navigation purposes, GetCatalogueFull also returns:

grouped wines or cuvées;
their individual vintage records;
the Vincod associated with each vintage record;
the publication status of each entry;
the standardized product name, when available.

It does not return the complete descriptive, technical, logistical or media information of each product.

Request

https://api.vincod.com/3/xml/owner/GetCatalogueFull/<LANGUAGE>/<VINCODOWNER>?apiKey=<YOURAPIKEY>

JSON format:

https://api.vincod.com/3/json/owner/GetCatalogueFull/<LANGUAGE>/<VINCODOWNER>?apiKey=<YOURAPIKEY>

HTTP method

GET

Parameters

Parameter	Location	Required	Description
`VERSION`	URL path	Yes	API version. Currently available in version `3`.
`FORMAT`	URL path	Yes	Response format: `xml` or `json`.
`TARGET`	URL path	Yes	API resource. Must be `owner`.
`METHOD`	URL path	Yes	API method. Must be `GetCatalogueFull`.
`LANGUAGE`	URL path	Yes	Language used for translated catalogue content, for example `fr`, `en`, `de`, `it` or `es`.
`VINCODOWNER`	URL path	Yes	vin.co identification code of the catalogue owner.
`apiKey`	Query string	Yes	Authorized API key associated with the owner or with an authorized API consumer.

Example request

https://api.vincod.com/3/xml/owner/GetCatalogueFull/fr/543PF3VXDN?apiKey=<YOURAPIKEY>

Purpose

The endpoint can be used to:

retrieve the complete catalogue hierarchy belonging to an owner;
reproduce the vin.co catalogue hierarchy in another application;
list the owner’s families, wineries, ranges, wines and individual vintage records;
identify the Vincod associated with each individual vintage;
synchronize a catalogue with a website or e-commerce platform;
perform an initial catalogue import without requesting each entity separately.

Catalogue hierarchy

Depending on the organisation of the owner’s catalogue, the response may contain several hierarchical levels:

Owner
├── Collection / Family
│   └── Brand / Winery
│       └── Range
│           └── Product / Wine
│               └── Years / Vintage
└── Brand / Winery
    ├── Range
    │   └── Product / Wine
    │       └── Years / Vintage
    └── Product / Wine
        └── Years / Vintage

Not every catalogue uses all these levels:

an owner may not contain families;
a winery may not contain ranges;
a wine may be attached directly to a winery;
a winery may contain both direct wines and ranges;
each wine may contain one or several individual vintage records.

Response structure

The XML response uses nested <menu> elements to represent the catalogue hierarchy.

The entity type is specified by the type attribute of each <menu> element:

owner
family
winery
range
wine

Individual vintage records are represented by repeated <vintageyears> elements placed directly inside a <menu type="wine"> element.

Despite its plural name, <vintageyears> is not a container containing <vintageyear> children. Each <vintageyears> element represents one individual vintage record.

Simplified XML response

<?xml version="1.0" encoding="UTF-8"?>
<owners>
    <menu vincod="OWNER_VINCOD" type="owner">
        <title>Owner name</title>
        <link>/OWNER_VINCOD</link>
        <actif>0</actif>
        <publish>1</publish>

        <menu vincod="FAMILY_VINCOD" type="family">
            <title>Family name</title>
            <link>/FAMILY_VINCOD</link>
            <actif>0</actif>
            <orpheline>0</orpheline>
            <publish>1</publish>

            <menu vincod="WINERY_VINCOD" type="winery">
                <title>Winery name</title>
                <link>/WINERY_VINCOD</link>
                <actif>0</actif>
                <orpheline>0</orpheline>
                <publish>1</publish>

                <!-- Optional range level -->
                <menu vincod="RANGE_VINCOD" type="range">
                    <title>Range name</title>
                    <link>/RANGE_VINCOD</link>
                    <actif>0</actif>
                    <orpheline>0</orpheline>
                    <publish>1</publish>

                    <menu vincod="GROUPED_WINE_VINCOD" type="wine">
                        <idvin>1234</idvin>
                        <title>Wine name</title>
                        <publish>1</publish>

                        <vintageyears
                            type="vintage"
                            vincod="VINTAGE_VINCOD_1">
                            <title>Wine name</title>
                            <name_standard>
                                Standardized product name, 2024
                            </name_standard>
                            <vincod>VINTAGE_VINCOD_1</vincod>
                            <publish>1</publish>
                        </vintageyears>

                        <vintageyears
                            type="vintage"
                            vincod="VINTAGE_VINCOD_2">
                            <title>Wine name</title>
                            <name_standard>
                                Standardized product name, 2023
                            </name_standard>
                            <vincod>VINTAGE_VINCOD_2</vincod>
                            <publish>1</publish>
                        </vintageyears>
                    </menu>
                </menu>

                <!-- A wine may also be attached directly to the winery -->
                <menu vincod="GROUPED_WINE_VINCOD" type="wine">
                    <idvin>5678</idvin>
                    <title>Wine name</title>
                    <publish>1</publish>

                    <vintageyears
                        type="vintage"
                        vincod="VINTAGE_VINCOD">
                        <title>Wine name</title>
                        <vincod>VINTAGE_VINCOD</vincod>
                        <publish>1</publish>
                    </vintageyears>
                </menu>
            </menu>
        </menu>
    </menu>
</owners>

The exact number and nesting of the <menu> elements depend on the organisation of the owner’s catalogue.

Main entities returned

Owner

The root menu element represents the catalogue owner.

Example:

<menu vincod="543PF3VXDN" type="owner">
    <title>Domaines Barons de Rothschild (Lafite)</title>
    <link>/543PF3VXDN</link>
    <actif>0</actif>
    <publish>1</publish>
    <!-- Child menu elements -->
</menu>

Element or attribute	Type	Description
`@vincod`	String	Vincod identifier of the owner.
`@type`	String	Entity type. The value is `owner`.
`title`	String	Owner name in the requested language.
`link`	String	Relative URL associated with the owner.
`actif`	Integer / Boolean	Indicates whether the entity is the active catalogue entry.
`publish`	Integer / Boolean	Publication status of the entity.
`menu`	Element, repeated	Child catalogue entries. In this feed, the direct children are families.

Family

A menu element with type="family" represents a catalogue family or collection grouping several wineries.

Example:

<menu vincod="35FZCOTQH8" type="family">
    <title>Châteaux Wines Bordeaux</title>
    <link>/35FZCOTQH8</link>
    <actif>0</actif>
    <orpheline>0</orpheline>
    <publish>1</publish>
    <!-- Winery menu elements -->
</menu>

Element or attribute	Type	Description
`@vincod`	String	Vincod identifier of the family.
`@type`	String	Entity type. The value is `family`.
`title`	String	Family or collection name in the requested language.
`link`	String	Relative URL associated with the family.
`actif`	Integer / Boolean	Indicates whether the family is the active catalogue entry.
`orpheline`	Integer / Boolean	Indicates whether the family is orphaned in the catalogue hierarchy.
`publish`	Integer / Boolean	Publication status of the family.
`menu`	Element, repeated	Wineries belonging to the family.

Winery

A menu element with type="winery" represents a winery, estate or brand.

Example:

<menu vincod="1687D1AVAD" type="winery">
    <title>Château Lafite Rothschild</title>
    <link>/1687D1AVAD</link>
    <actif>0</actif>
    <orpheline>0</orpheline>
    <publish>1</publish>
    <!-- Range or wine menu elements -->
</menu>

Element or attribute	Type	Description
`@vincod`	String	Vincod identifier of the winery.
`@type`	String	Entity type. The value is `winery`.
`title`	String	Winery, estate or brand name in the requested language.
`link`	String	Relative URL associated with the winery.
`actif`	Integer / Boolean	Indicates whether the winery is the active catalogue entry.
`orpheline`	Integer / Boolean	Indicates whether the winery is orphaned in the catalogue hierarchy.
`publish`	Integer / Boolean	Publication status of the winery.
`menu`	Element, repeated	Child ranges or wines.

A winery may contain:

wines directly;
ranges containing wines;
both structures.

Range

A menu element with type="range" represents a product range within a winery.

Element or attribute	Type	Description
`@vincod`	String	Vincod identifier of the range.
`@type`	String	Entity type. The value is `range`.
`title`	String	Range name in the requested language.
`link`	String	Relative URL associated with the range.
`actif`	Integer / Boolean	Indicates whether the range is the active catalogue entry.
`orpheline`	Integer / Boolean	Indicates whether the range is orphaned in the catalogue hierarchy.
`publish`	Integer / Boolean	Publication status of the range.
`menu`	Element, repeated	Wines belonging to the range.

The range level is optional.

Wine

A menu element with type="wine" groups the different vintages belonging to the same wine or cuvée.

Example:

<menu vincod="B2GCJF" type="wine">
    <idvin>3868</idvin>
    <title>Château Lafite Rothschild</title>
    <publish>1</publish>

    <vintageyears type="vintage" vincod="B2GCJF">
        <title>Château Lafite Rothschild</title>
        <name_standard>
            Château Lafite Rothschild, AOC Pauillac,
            Premier Grand Cru Classé, Rouge, 2024
        </name_standard>
        <vincod>B2GCJF</vincod>
        <publish>1</publish>
    </vintageyears>

    <!-- Other vintageyears elements -->
</menu>

Element or attribute	Type	Description
`@vincod`	String	Vincod exposed on the grouped wine entry.
`@type`	String	Entity type. The value is `wine`.
`idvin`	Integer	Internal identifier shared by the grouped wine or cuvée.
`title`	String	Wine or cuvée name in the requested language.
`publish`	Integer / Boolean	Publication status exposed for the grouped wine entry.
`vintageyears`	Element, repeated	Individual vintages associated with the wine.

Unlike the owner, family, winery and range levels, the wine node does not contain link, actif or orpheline elements in this feed.

The wine node is a grouping level. The individual product records that can be requested through other API endpoints are identified inside the repeated vintageyears elements.

Vintage

Each <vintageyears> element represents one individual vintage record associated with the parent wine.

Despite its plural name, vintageyears is not a container holding separate vintageyear child elements. The element itself is repeated once for each available vintage.

Example:

<vintageyears type="vintage" vincod="KA7A2F">
    <title>Château Lafite Rothschild</title>
    <name_standard>
        Château Lafite Rothschild, AOC Pauillac,
        Premier Grand Cru Classé, Rouge, 2023
    </name_standard>
    <vincod>KA7A2F</vincod>
    <publish>1</publish>
</vintageyears>

Element or attribute	Type	Presence	Description
`@type`	String	Always	Entity type. The value is `vintage`.
`@vincod`	String	Always	Vincod identifier of the individual vintage record.
`title`	String	Always	Wine or cuvée name in the requested language.
`name_standard`	String	Optional	Standardized full product name. It may include the winery, cuvée, appellation, classification, colour and vintage year.
`vincod`	String	Always	Vincod identifier of the individual vintage record. This duplicates the `vincod` XML attribute.
`publish`	Integer / Boolean	Always	Publication status of the individual vintage.

The vintage year is not returned in a dedicated element such as:

<vintageyear>2024</vintageyear>

When available, it is included in the name_standard value.

Consequently, integrations should not rely solely on parsing the final four digits of name_standard as a guaranteed source of the vintage year. The name_standard element is optional in this feed and may be absent for some vintage records.

The Vincod of the individual vintage should be used as its external vin.co identifier.

Condensed response

The entities returned by GetCatalogueFull must not be interpreted as complete owner, winery, range or product records.

In particular, this endpoint is not intended to return complete:

presentation fields;
technical specifications;
logistical information;
grape varieties;
media collections;
reviews;
recipes;
distributors or shops;
e-commerce offers.

To retrieve the complete data of an entity, use its Vincod with the corresponding dedicated endpoint.

Required data	Recommended endpoint
Complete owner information	`GetOwnerByVincod`
Complete winery or brand information	`GetWineryByVincod`
Complete range information	`GetRangeByVincod`
Complete wine or product information	`GetWineByVincod`

Implementation recommendations

Do not assume that every hierarchy level exists

An integration must support at least the following structures:

Owner > Winery > Wine > Vintage
Owner > Winery > Range > Wine > Vintage
Owner > Family > Winery > Wine > Vintage
Owner > Family > Winery > Range > Wine > Vintage

Treat repeated elements as collections

The following elements may occur multiple times:

menu;
vintageyears.

Depending on the XML-to-object or JSON parser used, a single occurrence and several occurrences may not be represented in the same way. The integration should normalize these values as collections.

Use Vincod identifiers

Titles and standardized names may vary according to language or content updates.

Use Vincod values as external vin.co identifiers rather than using title or name_standard.

Distinguish grouped wines from individual vintage records

The <menu type="wine"> element groups several vintage records using idvin.

The individual record to use with a detailed product endpoint is identified by the Vincod of the corresponding <vintageyears> element.

Evaluate publication status at each level

The response may contain entries with:

<publish>0</publish>

The presence of an entity in the response does not necessarily mean that it is published.

The consuming application must decide whether to retain, synchronize or display unpublished entities according to its own requirements.

Do not parse the vintage year as guaranteed structured data

The year may be included in name_standard, but this element is optional and is not a dedicated vintage field.

An integration should not assume that the last four characters of name_standard always represent a valid vintage year.

Recherche

Bienvenue sur le site support

Request

HTTP method

Parameters

Example request

Purpose

Catalogue hierarchy

Response structure

Simplified XML response

Main entities returned

Owner

Family

Winery

Range

Wine

Vintage

Condensed response

Implementation recommendations

Do not assume that every hierarchy level exists

Treat repeated elements as collections

Use Vincod identifiers

Distinguish grouped wines from individual vintage records

Evaluate publication status at each level

Do not parse the vintage year as guaranteed structured data