These fields should be used in preference to the other fields described in this document wherever possible. Through a more complex structure we are able to more accurately represent the industry's available deals and so better communicate them to customers, leading to improved conversion.
Note: The following standard fields should be downloaded alongside all the below fields as they aren't duplicated here:
Note: Majority of the JSON fields are not compatible with Landline, Broadband and TV deals except for [deal_type_json];[deal_extras_json]; [deal_costs_json] and [deal_retailer_json].
The "product" sits at the highest level of our product tree, and describes a conceptual product like an "iPhone" or a "Galaxy" phone. It belongs to a manufacturer/brand, and has a product type.
Note: Using the [product_id] you can group all "Galaxy" products together or all "iPhone" products together (for example).
Note: The [product_name] can be appended to the [product_brand] to arrive at a more complete product name: [product_brand] + [product_name] = "Apple iPhone".
{
"product_id": "2021",
"product_name": "Lumia",
"product_brand": "Nokia",
"product_brand_id": "20",
"product_type": "Mobile Phone",
"product_type_id": "1"
}
Note: this could be different from the manufacturer, so for instance a "Google Nexus 6" is branded "Google" but is manufactured by Motorola. Wherever possible we will specify the branding rather than the manufacturer. Similarly the "EE Kestrel" is manufactured by Huawei, but will be branded "EE" in our data.
The "product version" sits below the "product" in the product hierarchy and describes at a reasonably high level the product in the range. Examples would be (Apple iPhone) "5s" or (Samsung Galaxy) "S4". Using the [product_version_id], all the different colours and capacities of Samsung Galaxy S4 could be grouped together, or we can filter on just Apple iPhone 5C, and see all the colours and capacities that are available.
The [product_version_name] can be appended to [product_name] and [product_brand] to arrive at the complete product version name: [product_brand] + [product_name] + [product_version_name] = "Apple iPhone 5S".
{
"product_version_id": "421",
"product_version_name": "735"
}
The "product edition" is the lowest level of the product hierarchy and describes a specific product being sold. Examples would be (Apple iPhone 5S) "16GB White" or (Samsung Galaxy S4) "32GB Blue".
Note: in practice, the capacity and colour will act as the defining features of this edition (separating it from other editions under the same [product_version]), but in future other defining features could emerge.
Note: the capacity and colour are described in a structured way in the [device_features_json] field so there is no need to parse the [product_edition_name] field.
The full product name can be derived by using the [product_brand], [product_name], [product_version_name] and [product_edition_name] together: e.g. "Apple iPhone 5S 16GB White".
{
"product_edition_id": "759",
"product_edition_name": "Black",
"reseller_product_edition_id": "1234"
}
More image types could be added in future. A note about images.
{
"primary_thumb": "http://example.com/images/55c5fedddb7cfaaaa07459f227cdf8e0.png",
"primary_large": "http://example.com/images/55c5fedddb7cfaaaa07459f227cdf8e0.png"
}
This field contains product attributes that can be used for filtering and grouping of products.
Note: the values can be empty for product types where the feature does not apply (for instance Televisions don't have a SIM Card Type), and as a result the key may not appear. See Specifications and Features availability for more information.
{
"colour": "Deep Black",
"colour_group": "Black",
"max_data_standard": "4G",
"condition_grade": "Grade A",
"condition": "Used",
"condition_friendly": "Good As New",
"sim_type": "Nano SIM",
"capacity": "8GB",
"os": "Windows",
"megapixels": "7"
}
Note: this does not relate to the Network or tariff being purchased (as in, it's entirely possible to buy a 3G contract for a 4G device). The contract's data standard is described in [tariff_allowances_json] - cellular speed.
Note: where there is no 'friendly' description is available, the standard description is passed through in its place.
Note: older cameras can show as having a decimal value of less than 1 megapixel ("0.3" is VGA, for example), but all newer cameras will be rounded to the nearest megapixel. If no camera is available, this field will contain the text 'None'.
It is expected that specifications will not be used for filtering or grouping because many of the specifications are free text fields.
{
"display_resolution": "720 x 1280",
"display_size": "4.7\"",
"display_type": "AMOLED",
"primary_camera_flash": "LED",
"primary_camera_resolution": "1920 x 1080",
"internal_memory": "8GB",
"memory_card_slot": "microSD, up to 128GB",
"processor": "1.2 GHz Quad-core Cortex-A7",
"2g": "GSM 850/900/1800/1900",
"3g": "HSDPA 800/850/1900/2100",
"4g": "LTE 800/1800/2600",
"bluetooth": "4.0 with A2DP",
"gps": "A-GPS, GLONASS and Beidou",
"wifi": "802.11 b/g/n, DLNA, Wi-Fi hotspot",
"talk_time": "Up to 22 hours",
"secondary_camera": "5 Megapixels",
"weight_grams": "134",
"dimensions": "134.7 x 68.5 x 8.9 mm",
"chipset": "Qualcomm Snapdragon 400",
"battery_type": "Removable Li-Ion Battery",
"ip_rating": "Not rated"
}
Note: that many of the fields below have already been described in Standard Fields - specifications. Those fields that are unique to the JSON representation have been described below.
Note: sub-fields could still be empty if the relevant device does not have a certain specification. Where this is the case, the key will not be included. This is because not all specification types apply to all products. See Specifications and Features availability for more information.
General details of the Mobile Network Operator with whom the customer will have a contract.
{
"name": "O2",
"company_id": "21",
"logo_url": "https://www.o2.co.uk/upgrade/static/5daadbcde609d6de3da2221ba3fab7e6852c1de8/desktop/images/o2-logo-white.gif",
"coverage_url": "http://www.o2.co.uk/coveragechecker",
"terms_url": "http://www.o2.co.uk/termsandconditions",
"description": "O2 offer customers the option to upgrade their phone at any time with O2 Refresh, and priority rewards for all customers from everything to free Lattes to priority access to gig tickets and live events. With Priority from O2, you're always a VIP."
}
Note: In cases where the product does not belong to a Network (i.e. is SIM-Free or not a cellular device), the [name] and [company_id] values will be populated consistently as "No Network" and "76" respectively, but the other values can be blank. See also Skipping fields based on [network_details_json].
Note: that this is not always available for MVNOs.
Tariffs are often grouped by the networks. The tariff group allows for filtering/grouping of tariffs. Similar tariffs often have the same benefits, call charges etc. See also Displaying tariff information.
{
"tariff_group_id": "337",
"tariff_group_description": "With O2's Big Bundles Pay and Go tariff not only can you access O2 perks like Priority, you can also choose from a range of flexible 30-day contracts and go as big as you want.",
"tariff_group_promo_info": ""
}
Note: In cases where the product is sold without a contract (as in the case of SIM-Free phones, or some wearable devices), the [tariff_group_description] field can be empty. In all other cases it should be populated. See also Skipping fields based on network_details_json.
Note: it is important to display promotional information when it is available as it could materially affect the product the customer is purchasing. This field can (and often will) be empty.
Contains details of the specific tariff being purchased. See also Displaying tariff information.
{
"tariff_id": "1557",
"tariff_name": "O2 Big Bundles £20",
"tariff_type_id": "5",
"tariff_type": "Phone Pre-pay",
"tariff_term": "0",
"tariff_term_friendly": "0 Month(s)",
"tariff_promo_info": "This Big Bundle lasts one calendar month, and is activated when you first top up at least £20. Your bundle will automatically renew each calendar month provided you have at least £20 credit in your account on your monthly anniversary date."
}
Note: To determine whether or not the device comes with a contract you can check for the value of "11" in [tariff_details_json] - tariff_type_id or "76" in [network_details_json] - company_id. See also Skipping fields based on network_details_json.
Note: The tariff_type_id gives no indication of whether the deal is a "SIM Only" type deal (i.e. without a device included). In order to determine whether the deal comes with or without a device, check the [device_product_json] - product_type_id field for a value of 2 (SIM Card).
Note: it is important to display promotional information when it is available as it could materially affect the product the customer is purchasing. This field can (and often will) be empty.
Contains details of all the allowances that come with this tariff. See also Displaying tariff information.
{
"mins_details": {
"cross_net_anytime": "400",
"cross_net_anytime_qualifier": "UK",
"same_net_anytime": "",
"special_numbers_see_terms": "",
"landline": ""
},
"texts_details": {
"cross_net_anytime": "4000",
"same_net_anytime": ""
},
"data_details": {
"wifi_mb": "",
"cellular_mb": "2000",
"cellular_speed": "4G Internet"
}
}
Note: All these fields are optional, and depend on the type of contract tied to the deal (if any). To determine whether or not it's worth your code checking through this field, you can look for the presence of "11" in [tariff_details_json] - tariff_type_id or "76" in [network_details_json] - company_id. See also Skipping fields based on network_details_json.
Note: Wherever the product does come with a contract, you should find data in these fields, though exactly which ones are populated will depend on the type of contract (for instance Mobile Broadband deals don't come with minutes and texts). In most cases, it is best for your page to 'fail gracefully' - i.e. intelligently show or hide fields based on the presence of a value.
Note: In many cases Pay-as-you-go tariffs can have inclusive minutes/texts/data/etc. when purchased with an appropriate topup, so it's best not to rely on assumptions about contract types (related to the above point).
Note: sometimes unlimited wifi is included as a benefit of being on the network or under certain circumstances like on the london underground. This won't be represented here, but instead will be shown in [deal_extras_json].
Contains details of pence-per-minute or pence-per-MB style charges when the customer uses up all their inclusive allowances (or where there's no inclusive allowance). See also Displaying tariff information.
{
"pence_per_cross_net_min": "35",
"pence_per_cross_net_text": "12",
"pence_per_mb": "300",
"data_charge_text": "",
"pence_per_voicemail_min": "15"
}
Note: All these fields are optional, and depend on the type of contract tied to the deal (if any). To determine whether or not it's worth your code checking through this field, you can look for the presence of 11 in [tariff_details_json] - [tariff_type_id] or 76 in [network_details_json] - company_id. See also Skipping fields based on network_details_json.
Note: Wherever the product does come with a contract, you should find data in these fields, though exactly which ones are populated will depend on the type of contract (for instance Mobile Broadband deals don't come with minutes and texts). In most cases, it is best for your page to 'fail gracefully' - i.e. intelligently show or hide fields based on the presence of a value.
Describes the type of sale to allow appropriate filtering. Valid values are currently limited to:
{
"deal_type_id": "0",
"deal_type_name": "Consumer"
}
Extras are split into high-level Groups (like "Free Gifts", or "Discounts & Loyalty", for instance), and within those groups Extras are further sub-categorised into Source Types. Everything is given a consistent ID and so Groups and Types can be grouped/filtered as required within your code. See also Displaying tariff information.
{
"groups": [
{
"id": "2",
"Inclusive Services": [
{
"id": "255-3",
"Service Attributes": [
{
"id": "13",
"groupingId": "M3",
"title": "BlackBerry Services",
"desc": "Use the internet, email and BBM on your BlackBerry to share messages, pictures and more for free. Sync with your PC or Mac and take your favourite music, photos and videos wherever you go."
}
]
},
{
"id": "255-5",
"Enhanced customer service": [
{
"id": "79",
"groupingId": "M5",
"title": "O2 Pay and Go Rewards",
"desc": "As a new customer, when you join O2 Pay & Go and opt into O2 Rewards, you''ll earn 5% back on all top-ups every three months. So, if you top up £50, you can get £2.50 back at the end of the quarter. Even better, after you''ve been with us for six months, the % of rewards you earn will increase to 10%."
}
]
},
{
"id": "255-11",
"Roaming services": [
{
"id": "73",
"groupingId": "M11",
"title": "O2 Travel",
"suffix": "For the length of your contract",
"desc": "O2 Travel is your perfect holiday companion.You can download TripAdvisor City Guides for reviews on things to do, the best places to eat and maps you can use offline. And if you are missing home, you can talk for up to an hour for a connection charge of just 50p and access all the data you need for just £1.99 per day."
}
]
},
{
"id": "255-4",
"Entertainment freebies and discounts": [
{
"id": "64",
"groupingId": "M4",
"title": "O2 Priority",
"suffix": "For the length of your contract",
"desc": "Priority from O2 gives you access to exclusive offers and events including lunch for £1 every Monday. Grab some VIP treatment for you and your friends with access to gig tickets up to 48 hours before general release, exclusive entry to O2 bars and side step the queues with fast track lanes at O2 venues."
},
{
"id": "65",
"groupingId": "M4",
"title": "O2 Tracks",
"suffix": "For the length of your contract",
"desc": "O2 Tracks gives you nonstop access to all the hottest music videos, top 40 playlists and backstage gossip. Try it for free with a four week free trial when you join O2 – no ads, no streaming, just great music."
}
]
},
{
"id": "255-23",
"Free or discounted allowances": [
{
"id": "68",
"groupingId": "M23",
"title": "O2 TU Go",
"desc": "TU Go is a free app that lets you use your O2 number on smartphones, tablets and laptops.It''s just like using your phone. Sign in to TU Go using a wifi connection to get your calls, texts and voicemail on up to 10 devices. The person you''re talking to doesn''t even need to have the app.Our latest version of TU Go now also lets you use the app over any mobile data (3G / 4G) connection – so you can now use TU Go for calls, texts and voicemails whenever you have mobile data available. If you want to use mobile data for TU Go calls, you can switch this on in Settings."
},
{
"id": "69",
"groupingId": "M23",
"title": "O2 WiFi Hotspots",
"desc": "Stay connected with O2 WiFi Hotspots available in thousands of locations nationwide including All Bar One, Debenhams, Café Rouge, Costa, House of Fraser, McDonalds and Subway."
}
]
},
{
"id": "255-25",
"Free or discounted software": [
{
"id": "80",
"groupingId": "M25",
"title": "Evernote Premium for a year",
"desc": "Experience Evernote Premium free for 1 year. With Evernote Premium you can capture your ideas, tasks, projects and more. You can share and edit your notes, access your work anywhere offline and get 1GB of free uploads each month."
}
]
}
]
},
{
"id": "4",
"Comes with (chargeable)": [
{
"id": "255-2",
"Pay as you go Top-up": [
{
"id": "5",
"groupingId": "M2",
"title": "Pay as you go Top-up: £20",
"suffix": "Topup",
"cost_type": "Fixed",
"cost": "20.00",
"desc": "This product comes with a mandatory top-up charged at £20, meaning you will have £20 credit to use (or on your account)."
}
]
}
]
}
]
}
Note: Additional Group Types may be added in future. When they are, they will be documented here.
Note: The list of Source Types will grow and change over time as new services and types of service are brought to market. It's therefore best to build your list of Source Types based on the contents of the data feed rather than the extract above, which is provided as an example only.
groups (Top Level) - beneath this is an array of Extra Groups Types and their details.
Note: Each Extra Group is contextually different, and their purposes are discussed below, though their structure is consistent.
extra source type (Second Level) - beneath this is an array of Extra Source Types and their details.
Note: Source Types allow us to subcategorise Extras. The Source Type can appear under more than one Group (for instance, allowances could be part of an inclusive service and/or a loyalty reward.)
extra (Third Level) - beneath this is an array of extras and each extra's details.
Contains details of the merchant (retailer) selling the deal. Note that this can be different from the Network the deal is being sold on.
{
"name": "O2",
"company_id": "21",
"logo_url": "https://www.o2.co.uk/upgrade/static/5daadbcde609d6de3da2221ba3fab7e6852c1de8/desktop/images/o2-logo-white.gif",
"terms_url": "http://www.o2.co.uk/termsandconditions"
}
Contains details of the deal's pricing both including and excluding VAT. Including VAT prices should be shown for consumer deals, whereas convention dictates that business-only deals be sold at exc. VAT prices. We have included both in case you need to mix and match business and consumer deals in the same list.
See Understanding Pricing for more information.
{
"upfront_inc_vat": "80.00",
"upfront_exc_vat": "83.33",
"upfront_previous_inc_vat": "100.00",
"upfront_previous_exc_vat": "83.33",
"monthly_total_inc_vat": "29.28",
"monthly_total_exc_vat": "24.40",
"monthly_total_previous_inc_vat": "28.78",
"monthly_total_previous_exc_vat": "23.98",
"monthly_device_inc_vat": "5.28",
"monthly_device_exc_vat": "4.40",
"monthly_device_term_months": "36",
"monthly_device_final_term_inc_vat": "",
"monthly_device_final_term_exc_vat": "",
"monthly_device_final_term_months": "",
"monthly_contract_inc_vat": "24.00",
"monthly_contract_exc_vat": "20.00",
"monthly_contract_term_months": "24",
"ecpm_inc_vat": "31.50",
"ecpm_exc_vat": "26.25",
"tco_inc_vat": "1134.08",
"tco_exc_vat": "945.07",
"price_rises": [
{
"date": "2025-04-01",
"price_rise": "1.00",
"new_airtime_cost_inc_vat": "25.00",
"new_monthly_cost_inc_vat": "30.28"
},
{
"date": "2026-04-01",
"price_rise": "1.00",
"new_airtime_cost_inc_vat": "26.00",
"new_monthly_cost_inc_vat": "31.28"
}
]
}
Note: Where the product is not being sold with a contract (check for "76" in [network_details_json] - company_id), any monthly fields should be ignored. See also Skipping fields based on network_details_json.
Note: Any _previous fields can be empty where no previous price exists.monthly_contract_ and monthly_device_ fields will be empty where the contract isn't a split-price deal.
Price-rises object:
Details the discounts available with this deal, split into network and retailer discounts (the two can co-exist). A retailer discount is often supplied on a redemption (customer must claim) or automatic (sent in the post after x days) basis, and payment will usually arrive by cheque or bank transfer. By contrast a network discount is usually discounted at source, and so the customer will see the discount applied to their monthly bill.
See Grouping and Filtering Cashbacks.
{
"network_discount": {
"nd_reduction_type_id": "4",
"nd_payment_type_id": "64",
"nd_requires_promo_code": "0",
"nd_value": "50",
"nd_duration_in_months": "3",
"nd_description": "Pay only 50% for 3 months (automatic)"
},
"retailer_discount": {
"rd_reduction_type_id": "1",
"rd_payment_type_id": "32",
"rd_requires_promo_code": "0",
"rd_value": "850",
"rd_duration_in_months": "22",
"rd_description": "Pay only £8.50 for 22 months (by redemption)"
}
}
Note: Where a promotion code is required to support any given discount, this will be described in the fields: [tariff_group_details_json] - tariff_group_promo_info, [tariff_details_json] - tariff_promo_info or [deal_promo_info]. It is important therefore that all these fields can be passed through unaltered and presented on-site in order to support merchant promotional activity. Whether the promo info is stored at the tariff group, tariff, or deal level depends on to what extent this promotion is shared among other deals offered by the merchant.
Note: Empty entries will be excluded, so if there are no discounts of any sort, this field could be empty.
See Grouping and Filtering Cashbacks.
{
"id": "332",
"type_id": "2",
"type_name": "Cashback paid automatically",
"value": "60.00"
}
Note: This field will be empty where no cashbacks are available for this deal.
This field is currently not being used.