Data dictionary
Applies toQuery APIJobs API
This dictionary describes the option document — the record EDITED returns for a single product option (a style in one colour). Every field is listed with its type, a plain-English definition, and an example value.
Using MCP? The same underlying data is exposed through the MCP tools with their own field names; see the MCP Reference and the market_data_docs tool for the MCP field reference.
How to read this
- Not every field appears on every document. A field is omitted when EDITED has no value for it — for example, the discount fields are absent on an option that has never been discounted.
- Prices are integers, multiplied by 100 (so
26000means 260.00). This holds for every currency, including those with no minor unit — it is not a cents convention. Prices come in three forms: your chosen currency (default USD), the original retailer currency (the*_originalfields), and USD (the*_usdfields). - Fields whose name starts with an underscore (e.g.
_price) are calculated on request and are not returned by the Schema API. - Classification fields (categories, styles, details) carry EDITED IDs; resolve their human labels and valid values via the Schema API.
- An "option" is a style in one colour; a "SKU" is a single size of that option. All times are UTC.
Identifiers & linking
| Field | Type | Description | Example |
|---|---|---|---|
option_id | string (40 character hash) | EDITED's unique identifier for an option (a product at style and colour level). The option_id field is immutable between option documents over time, so would be a good field to use to link option documents (app: EDITED Option ID) | f355ad32ff70857f185788357825849f7439689c |
product_hash | string (40 character limit) | Universal EDITED ID that connects linked SKUs. Linked SKUs can be found in the SKUs field of the option document (app: EDITED Product ID) | b7dfc8577acbaa6acc42f115 |
retailer_product_id | string | A code usually relating to product at style level from the retailer's site. There may be many SKUs associated with this one ID. The retailer_product_id field is immutable between option documents over time, so would be a good field to use to link documents (app: Retailer Product ID) | 22026692 |
Retailer, brand & market
| Field | Type | Description | Example |
|---|---|---|---|
retailer | string | Retailer name (app: Retailer) | farfetch-bh |
market | string | The retailer region (app: Markets) | US |
tier | string | One of: 'Value', 'Mass', 'Premium', 'Luxury'. Retailer's market segment (app: Segment) | luxury |
outlet | true/false | Whether an option comes from an outlet retailer, or a retailer's outlet branch (app: Outlet) | false |
brand | string | The option brand, normalised across EDITED's dataset. Use the Brands endpoint in the Schema API to find the normalized values. (app: Brand) | Love Moschino |
brand_slug | string | A short representation of the option's normalised brand name with no spaces or special characters. For brands with no spaces or special characters, this field will not be present. | love-moschino |
retailer_brand | string | The option brand as collected on the retailer site. Use the Brands endpoint in the Schema API to find the normalized values. | Love Moschino |
retailer_brand_slug | string | A short representation of the option's brand name as collected on the website with no spaces or special characters | love-moschino |
is_petite_size | true/false | Whether an option is a specialized petite size brand. (app: Petite Brands) | false |
is_plus_size | true/false | Whether an option is a specialized plus size brand. (app: Plus Size Brands) | false |
is_second_hand | true/false | Whether an option is a specialized secondhand retailer. (app: Second Hand Retailers) | false |
is_tall_size | true/false | Whether an option comes from a specialized tall size brand. (app: Tall Brands) | false |
Product attributes
| Field | Type | Description | Example |
|---|---|---|---|
name | string | Name of the option (translated into English) (app: Name) | logo-plaque leather pumps |
name_untranslated | string | Name of the option as it appeared on the retailer's site, in the original retailer language | logo-plaque leather pumps |
description | array of strings | Option description provided on the retailer's website (translated into English) (app: Description) | [ "fuchsia pink", "calf leather", "Gold-tone logo lettering", "logo tag", "branded lea… |
description_untranslated | array of strings | Option description provided on the retailer's website, in the original retailer language | [ "fuchsia pink", "calf leather", "Gold-tone logo lettering", "logo tag", "branded lea… |
lang | string | ISO code denoting the original language the option is presented in | fi |
colour_name | string | Name of the option (its colour) (app: Option) | blueprint |
care | array of strings | An array of care and composition information as seen on the retailer's website (app: Care) | ["Content: 100% nylon; Fill: 90% goose down, 10% goose feathers", "Care: Hand wash"] |
composition | array of objects | Keys are 'material' (str) and 'percentages' (array of floats). List of composition values extracted from the care field. 'material' is the extracted material value, and 'percentages' is a list of percentages associated with the material (in the range 0 to 100). The percentages list may contain multiple values if the material appeared multiple times, or it may contain null if no percentage information was found for the material. | — |
custom_fields | array of objects | List of custom crawler fields with key key and value value. These only exist for certain crawlers and can contain various retailer IDs and information. See FAQ for more info. A reminder that it is possible to query a nested field using syntax like custom_fields/key="search term" | field_name: value |
url | string | URL of the product page on the retailer website | https://www.farfetch.com/bh/shopping/women/love-moschino-logo-plaque-leather-pumps-item-2… |
image_urls | array of hyperlinks | Hyperlinks for all images related to the option. | ["https://product-images.edited.com/ebec0c34f92c9447d9532075/19cab4c4a3/full.jpg", "https… |
merch_info | array of strings | Information that the retailer has provided about how the product is merchandised (app: Offers and Promotional Information History) | ["ONLINE EXCLUSIVE"] |
has_current_merch_info | true/false | Whether the option currently has merchandising information (e.g. Online Only) visible on the retailer's product page | false |
has_had_merch_info | true/false | Whether EDITED has seen merchandising information (e.g. Online Only) visible on the retailer's product page at least once | true |
EDITED classification
| Field | Type | Description | Example |
|---|---|---|---|
category | array of strings | List of values denoting the section of the retailer site in which the option is listed | ["Sale", "the little puff vest"] |
cs_grp | string | EDITED's top level classification IDs for the option (e.g. outerwear, footwear, bottoms). These categorisations are mutually exclusive so an option will only appear in one. Valid values and their mapped labels can be found in the Searches endpoint of the Schema API. | outerwear |
cs_subcategory | string | EDITED's second level classification of an option (e.g. sub_cat_shorts_bottoms, sub_cat_coat_outerwear). These are mutually exclusive so an option will only appear in one. Valid values and their mapped labels can be found in the Searches endpoint of the Schema API. | sub_cat_coat_outerwear |
cs_style | string | EDITED's third and most granular classification of an option (e.g. style_bermuda_shorts_bottoms, style_other_coat_outerwear). These are mutually exclusive so an option will only appear in one. Valid values and their mapped labels can be found in the Searches endpoint of the Schema API. | style_other_coat_outerwear |
product_searches | array of strings | The product_searches_data field gives the mapping of IDs to the categorisation names Category, subcategory and style classifications that this options appears in (app: Categories) | ["Footwear", "Shoes", "Court/Pump"] |
product_searches_data | array of objects | Product category IDs and names this option is associated with (app: Categories) | [{ "id": 555, "name": "Footwear"}, {"id": 764, "name": "Shoes"}, {"id": 833, "name": "Cou… |
product_details | array of strings | The product_detail_data field gives the mapping of IDs to the detail names The details detected on this option (app: Details) | ["Flat", "Fabrication", "Leather (incl faux leather)", "Footwear" ] |
product_details_data | array of objects | Product detail IDs and names this option is associated with (app: Details) | [{ "id": 68,"name": "Flat"}, { "id": 276, "name": "Fabrication"}, {"id": 50, "name": "Lea… |
gender | string | Valid categories are: men, women, girls, boys, unisex-kids and unisex-adults. Gender category of the option (app: Genders) | women |
season | string | EDITED's inferred season based on the option region and date it was first seen (app: Season) | ss24 |
predominant_colour | string | The name of the predominant colour detected on the option image (app: Colors) | fuschia |
predominant_pattern | string | One of: 'abstract', 'animal', 'aztec', 'camouflage', 'checks', 'conversational', 'floral', 'geometric', 'graphics', 'lace', 'paisley', 'plain', 'sports', 'stripes', 'tile'. The name of the predominant pattern detected on the option image (app: Patterns) | plain |
predominant_tpx_code | string | The precise tpx-code of the most prominent colour detected on the option image | 18-2140 |
colours | array of objects | List of colours that the option features including the name and the tpx code of the colour detected. The 'offset' is a zero indexed order of prominence of the colours in the picture. The 'ratio' is a measure of that colour's prominence. Dictionary keys are 'basic_name' (string), 'offset' (int), 'ratio' (float), 'tpx_code' (str). (app: Product Colors) | — |
detail_denim | true/false | Detail for apparel, limited to: tops, bottoms, outerwear, dresses, product_sets and all_in_one. Describes whether the product is denim or not. | false |
detail_footwear_heeled | true/false | Detail for footwear options only, describes whether the option is heeled or not | false |
detail_sportswear_sport | string | Valid sports are: american football, baseball, basketball, boxing, cycling, football (soccer), golf, handball, hiking, hockey, lacrosse, rugby, running, snowsports, softball, tennis, training, volleyball, yoga, other. Detail for any kind of option, describes which sport the option is related to | style_training_sportswear |
licensed_activewear | true/false | Whether the option matches EDITED filters for detecting if it is a licensed activewear item (app: Licensed Activewear) | false |
lifestyle_activewear | string | Whether the option is performance (sports-activewear), lifestyle (lifestyle-activewear), or non-activewear (not-activewear). (app: Lifestyle) | sports-activewear |
Pricing & currency
| Field | Type | Description | Example |
|---|---|---|---|
_price | float | The price in your chosen currency that the option's cheapest SKU was listed at on the date seen multiplied by a factor of 100. (app: Current Price) | 26000 |
_price_original | float | The price in the original currency that the option's cheapest SKU was listed at on the date seen multiplied by a factor of 100. (app: Current Price) | 26000 |
price_usd | float | The price in USD that the option's cheapest SKU was listed at on the date seen multiplied by a factor of 100. (app: Current Price) | 26000 |
_advertised_price | float | The selling price of the option's cheapest SKU, in your chosen currency (default USD), multiplied up by a factor of 100 (app: Current Price) | 6860 |
_advertised_price_original | float | The selling price of the option's cheapest SKU in the original currency multiplied up by a factor of 100 (app: Current Price) | 6860 |
advertised_price_usd | float | The selling price of the option's cheapest SKU in USD multiplied up by a factor of 100 (app: Current Price) | 6860 |
_advertised_previous_price | float | The highest selling price for the option as advertised by the retailer, in your chosen currency (default USD), multiplied up by a factor of 100. EDITED may never have seen the option sold at this price (app: Advertised Full Price) | 9800 |
_advertised_previous_price_original | float | The highest selling price for the option as advertised by the retailer, in the original currency multiplied up by a factor of 100. EDITED may never have seen the option sold at this price (app: Advertised Full Price) | 9800 |
advertised_previous_price_usd | float | The highest selling price for the option as advertised by the retailer, in USD multiplied up by a factor of 100. EDITED may never have seen the option sold at this price (app: Advertised Full Price) | 9800 |
_first_price | float | The selling price of the option's cheapest SKU at the time it was first seen by EDITED on the retailer's site, in your chosen currency (default USD), multiplied up by a factor of 100 (app: First Price) | 26000 |
_first_price_original | float | The selling price of the option's cheapest SKU at the time it was first seen by EDITED on the retailer's site, in the original currency multiplied up by a factor of 100 (app: First Price) | 26000 |
first_price_usd | float | The selling price of the option's cheapest SKU at the time it was first seen by EDITED on the retailer's site in USD multiplied up by a factor of 100 (app: First Price) | 26000 |
_full_price | float | The highest price EDITED has ever seen the option at, in your chosen currency (default USD), multiplied up by a factor of 100. (app: Full Price) | 26000 |
_full_price_original | float | The highest price EDITED has ever seen the option at, in the original retailer currency, multiplied up by a factor of 100. (app: Full Price) | 26000 |
full_price_usd | float | The highest selling price that EDITED has ever seen the option at, in your chosen currency (default USD), multiplied up by a factor of 100. If the price of a product increases from that when it was first seen, this will become the new full price. (app: Full Price) | 26000 |
currency | string | Currency in which option price is listed on the retailer site (app: Currency) | USD |
_normalisation_fx_rate | float | The exchange rate used to initially convert the price in the original currency into USD. Multiply an original currency price by this to get USD | 1 |
_original_fx_rate | float | The exchange rate taken from the date we crawled the option, used to calculate the original prices on the retailers site from the USD value. The reciprocal of _normalisation_fx_rate. Divide original currency price by this to get USD. | 1 |
_user_fx_rate | float | The exchange rate taken from the date we crawled the option, used to convert into your requested currency (from the query string of your request) | 1 |
Discounts & price movement
| Field | Type | Description | Example |
|---|---|---|---|
discounted | true/false | Whether the product is currently discounted | false |
discount_percentage | float | Current level of discounting (percentage) | 0 |
deepest_discount_percentage | float | The greatest level of discounting that EDITED has tracked on an option based on previously seen and current prices | 30.0 |
first_discount_percentage | float | The percentage level of discounting seen by EDITED the first time the price of a option was reduced | 10.0 |
advertised_discounted | true/false | Whether the option was seen as advertised discounted by EDITED on the date given in date_seen | true |
advertised_discount_percentage | float | The percentage difference between the advertised previous price and the option's current price (app: Advertised Discount) | 30.0 |
deepest_advertised_discount_percentage | float | The greatest advertised level of discounting that EDITED has seen for a option, as advertised by the retailer | 30.0 |
first_advertised_discount_percentage | float | The first discount level (percentage) that EDITED has seen for the option, only as advertised by the retailer | 10.0 |
has_had_discount | true/false | Whether EDITED has seen the option discounted at least once, regardless of whether this discount was advertised by the retailer | true |
has_had_advertised_discount | true/false | Whether EDITED has seen the option advertised as discounted at least once | true |
price_increased | true/false | Whether the option's price has risen above the lowest price EDITED previously saw — true when at least one SKU is currently priced above its own lowest-seen price. | false |
price_increase_percentage | float | The largest percentage by which any of the option's SKUs is currently priced above its own lowest previously-seen price. The upward counterpart of discount_percentage (which measures the drop below the highest previously-seen price). | 0 |
price_increased_vs_last_percentage | float | The largest percentage by which any SKU's price rose compared with the last price EDITED saw for it — the increase since the previous observation (the price-up-vs-last action), rather than against the lowest-ever price. | — |
date_first_discount | string of date (UTC) in ISO format (YYYY-MM-DD) | The date the product was first found to be discounted (app: First discounted) | 2023-11-22 |
days_to_first_discount | int | The number of days between the date the option was first seen by EDITED and the date the option was first seen discounted (app: myE: Days to First Discount) | 111 |
Stock, availability & lifecycle
| Field | Type | Description | Example |
|---|---|---|---|
in_stock | true/false | Whether at least one linked SKU was shown as in stock. On the /option_history endpoint this reflects stock at that historical date. Stock status may be inferred (carried forward) for recent dates rather than freshly observed — see the inferred field. (app: In Stock) | true |
inferred | true/None | Present and true when this option document's values were carried forward (inferred) rather than freshly observed on the date seen. Documents built entirely from a fresh observation omit this field. To restrict a query to freshly observed data, filter on not_inferred. | true |
actions | string | Change-events detected for the option on the date seen, relative to the previous observation. Actions are identified per SKU and then deduplicated to the option. See the Change actions section for the full vocabulary. | [price-up] |
sku_count | int | Total number of linked SKUs for the option — the length of the skus array — regardless of in-stock status. | 27 |
sku_count_current | int | The number of sizes offered for an option that are in stock as of the date seen. | 1 |
_num_sizes | float | The number of distinct sizes among the option's SKUs. Usually equals sku_count; it is smaller when the same size appears in more than one SKU record (duplicate or variant listings). | 27 |
sellout_percentage | float | The percentage of SKUs linked to this option that have sold out | 96.2962962962963 |
restock_count | int | Number of times a replenishment has occurred, whereby more than 51% of all linked SKUs for an option have come back into stock (app: Replenishments) | 0 |
days_in_stock | int | Of the days between date found and date seen, how many days the option was fully in stock. | 445 |
date_ranges_in_stock | array of objects | The specific date ranges where at least one sku for the option was in stock. | [ { "gte": "2023-08-03", "lt": "2024-10-18" }, { "gte": "2024-10-22", "lt": "2024-10-… |
date_found | string of date (UTC) in ISO format (YYYY-MM-DD) | The date the option was first seen by EDITED (app: New in) | 2023-08-03 |
date_seen | string of datetime (UTC) in ISO format (YYYY-MM-DDThh:mm:ss (eg 1997-07-16T19:20:30)) | The latest date this option was seen by EDITED, in effect the 'current'* date for this option document | 2024-10-24T00:19:08 |
date_generated | string of date (UTC) in ISO format (YYYY-MM-DD) | The date when this data was last updated in EDITED's data store. This is modified when historical data is reprocessed to add or update data values and does not necessarily mean that data was collected from the retailer on this date | — |
schema_version | string | The version of the schema as it was on the date this option was processed by EDITED. This schema version can be used to make a request to the Schema API | 2018-04-18 |
date_first_sellout | string of date (UTC) in ISO format (YYYY-MM-DD) | The first date on which all of the option's linked SKUs were out of stock at once — a complete sellout, after the option had been in stock. (app: First sell out) | 2024-10-08 |
days_to_first_sellout | int | The number of days between date_found and date_first_sellout (the first date all of the option's linked SKUs were out of stock). | — |
date_first_majority_sku_sellout | string of date (UTC) in ISO format (YYYY-MM-DD) | First date at least 51% of SKUs linked to this option have gone out of stock. Linked SKUs can be found in the SKUs field of the option document (app: First majority sell out) | 2024-10-08 |
days_to_first_majority_sku_sellout | int | The number of days between the date the option was first seen by EDITED and the date 51% of its linked SKUs were seen out of stock. Linked SKUs can be found in the SKUs field of the option document (app: myE: Days to First Majority SKU Sellout) | 432 |
days_to_first_sellthrough | int | The number of days between date_found and the first date some (but not all) of the option's linked SKUs were out of stock — when the option first began selling through. Distinct from a complete sellout (see date_first_sellout). | 0 |
date_full_restock | string of date (UTC) in ISO format (YYYY-MM-DD) | The date the option was first fully restocked — when its linked SKUs went from at least 51% out of stock back to all in stock. | — |
days_to_full_restock | int | The number of days between the date the option was first seen by EDITED and the date the SKUs linked to the option were first replenished, that is that they went from at least 51% of them being out of stock to all of the linked SKUs being in stock | 30 |
Sizes & SKUs
| Field | Type | Description | Example |
|---|---|---|---|
normalised_sizes | array of strings | A list of 'normalised_size' values from all 'skus'. Normalised sizes are EDITED standard sizes that correspond to the retailer's SKU size. | — |
skus | array of objects | Details of the individual sizes (SKUs) | — |
Reviews
| Field | Type | Description | Example |
|---|---|---|---|
normalised_average_rating | float | Product overall rating normalised to a 5 point scale. (note that this average often includes ratings for multiple options [colors] of a product) | 4.58 |
number_of_reviews | int | Count of reviews for the product on the site (note that this count often includes reviews for multiple options [colors] of a product) | 52 |
Change actions
The actions field reports change-events detected for the option on its date_seen, relative to the previous observation. Possible values:
| Action | Meaning |
|---|---|
new | The option (or a SKU) was seen for the first time. |
stock-in | At least one SKU went from out of stock to in stock. |
stock-out | At least one SKU went from in stock to out of stock. |
restock | The majority of SKUs came back into stock. |
price-down | At least one SKU hit a new low price (lower than the lowest ever seen for that SKU). |
price-up | At least one SKU hit a new high price (higher than the highest ever seen for that SKU). |
price-down-vs-last | At least one SKU has a lower price than the last price seen. |
price-up-vs-last | At least one SKU has a higher price than the last price seen. |
first-price-down | The option was discounted for the first time. |
new-full-price | At least one SKU set a new all-time high price for the option. |
Sub-objects
Two fields contain arrays of nested objects.
SKUs — per-size records
The skus field is an array of per-size records. Each object describes one size (SKU) of the option. Fields may be absent when EDITED has no value for them.
| Field | Type | Description | Example |
|---|---|---|---|
sku_id | string | Unique identifier for the SKU (an option at a specific size). | fuschia pink_34 |
size | string | The size as listed on the retailer's site. | 34 |
option_name | string | The option's name (its colour) for this SKU. | fuschia pink |
option_name_untranslated | string | The option's name in the original retailer language. | fuschia pink |
normalised_sizes | array of strings | EDITED-standard size(s) corresponding to the retailer's size label. | — |
_price | float | The SKU's price in your chosen currency (default USD). Multiplied up by a factor of 100. | 26000 |
price_usd | float | The SKU's price in USD. Multiplied up by a factor of 100. | 26000 |
currency | string | Currency the SKU price is listed in on the retailer's site. | USD |
out_of_stock | boolean | Whether this SKU is out of stock. Defaults to false; if absent, assume in stock. | true |
custom_fields | array of objects | Retailer-specific custom crawler fields, as key/value pairs. | — |
Colours
The colours field is an array of detected colours for the option, ordered by prominence in the image.
| Field | Type | Description | Example |
|---|---|---|---|
basic_name | string | The colour family of the TPX code. | blue |
tpx_code | string | A specific colour code from the Pantone TPX system. | 15-4312 |
offset | int | Zero-indexed order of prominence of the colour in the image. | 0 |
ratio | float | A measure of that colour's prominence. | 1.419558677 |
Related
- The data — what EDITED's data covers and how it is structured.
- MCP Reference — the field and tool reference for EDITED MCP.
- API reference — the Query API and Jobs API endpoints that return this document.