JSON Fields | Mobile Phones

Nested fields

• product_id - Unique ID.
• product_name - Name of product.
• product_brand - The primary product's branding.

  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.

• product_brand_id - The brand ID is unique and will persist even if a brand name changes (for instance RIM changed to BlackBerry in the past).
• product_type - A catergorised text-name for the product. See Product Type valid values for insight to what values you can expect.
• product_type_id - These IDs are unique and persist even if a product type's name changes.

Nested Fields

• product_version_id - Unique ID.
• product_version_name - text name, for example "S4". This can be empty in cases where the [device_product_json] - product_name field sufficiently describes the product (so, there probably aren't multiple versions of this product as is the case with iPhones).

Nested Fields

• product_edition_id - Unique product edition ID.
• product_edition_name - Product edition name, for example "16GB White". This can be empty in cases where the [device_product_json] - product_name and/or [device_product_version_json] - product_version_name fields adequately describe the product (so there probably aren't multiple editions (colours, capacities, etc.) of this product, as there are with iPhones).
• reseller_product_edition_id - Unique identifier that defines the product at a reseller level (for instance there might be one reseller_product_edition_id for a New product, and another for Refurbished models). No two resellers will ever share [reseller_product_edition_ids], but they will share [product_id], [product_version_id], and [product_edition_ids].

Nested Fields

• primary_thumb - Thumbnail image URL.
• primary_large - Large image URL.

Nested Fields

• colour - This is the device's 'marketing colour'. It is unlikely to be generic enough to use for filtering or grouping but could be used as a secondary filter if needed.
• colour_group - Used for filtering/grouping. The list of acceptable values here has been reduced to a sensible minimum. You won't find any "ruby red" or "sunset orange" style values here, just "red" and orange". See Colour Group valid values for insight to what values you can expect.
• max_data_standard - The device's maximum available data standard. Valid values are "2G", "3G", "4G" and "5G".

  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.

• condition - Is either "New" or "Refurbished" and should be used for grouping/filtering.
• condition_grade - Is either blank (the product is either "New" or "Refurbished") "Grade A" (excellent condition), "Grade B" (could have some light scratches and marks), and "Grade C" (more visible marking / visibly used).
• condition_friendly - This should be displayed on your page in place of "New" or "Refurbished" if available and represents the merchant or Network's preferred wording (for instance EE prefer "Good As New" instead of "Refurbished"). In some cases there could be legal implications, so [condition_friendly] should be displayed in place of [condition] wherever possible.

  Note: where there is no 'friendly' description is available, the standard description is passed through in its place.

• sim_type - Valid values for this are currently limited to: "Combi SIM" (used for SIM cards only), "Standard SIM", "Nano SIM", "Micro SIM". Note that "Micro SIM" and "Standard SIM" devices can be used with "Combi SIM" SIM Cards.
• capacity - The device's internal storage rounded up or down to the nearest GB (in line with the product's marketing, where possible).
• os - The device's operating system, where known. Valid values are currently: "Android", "Apple iOS", "Badu", "BlackBerry", "N/A", "Proprietary", "Tizen", "Windows".
• megapixels - Text describing the number of megapixels the device's camera has available.

  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'.

Nested Fields

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.

• display_resolution - This field could be used for filtering/grouping devices if required as the number of different resolutions on the market is relatively small.
• display_size - The values here are always consistent (as in, we don't mix 2.1" and 2.1 inches).
• display_type - A text description of the type of display (like "Super AMOLED", etc.).
• primary_camera_flash - Could be used for grouping as the number of available values is limited.
• primary_camera_resolution - The device's primary camera resolution in W x H pixels. This field could be used for grouping if required, but the megapixels value in [device_features_json] is probably more useful.
• internal_memory - The amount of internal storage the device ships with. This value can be quite specific, and will end with either "MB" or "GB".
• memory_card_slot - The type of memory card slot, and the maximum card capacity (if known.
• processor - Details of the device's processor (where known).
• 2g - A list of 2G frequency bands on which this device can operate
• 3g - A list of 3G frequency bands on which this device can operate
• 4g - A list of 4G/LTE frequency bands on which this device can operate
• bluetooth - The bluetooth version number will always be at the beginning of the string and will be a decimal like "2.0", "2.1", "4.2". This will be followed by any text describing the additional/supported Bluetooth features of the device as advertised by the manufacturer.
• gps - The supported GPS standards of the device.
• wifi - The supported WIFI standards of the device.
• talk_time - Will contain text in the format "Up to x hours". Talk time is always rounded up to the nearest hour for simplicity and to allow for easier filtering/grouping.
• secondary_camera - Details of the device's secondary or rear-facing camera if available.
• weight_grams - This can be used for grouping/filtering in a range, as the value is just a simple integer.
• dimensions - Always in the format "H x W x D mm".
• chipset - Details of the device's chipset (where known).
• battery_type - States whether the battery is removable or not, and the primary battery technology used (like "Li-Ion", for example)
• ip_rating - Describes the device's weatherproofing capabilities along with its IP rating where known.

Nested Fields

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].

• name - Name of the Network
• company_id - The unique ID of this company. This could be the same as the retailer ID where the Network and the Reseller are the same (for instance O2 direct).
• logo_url - The URL containing the Network's logo for use in comparison lists or outbound links
• coverage_url - The Network's coverage checker URL.

  Note: that this is not always available for MVNOs.

• terms_url - The Network's general terms and conditions URL. Note that this could be different from the retailer's own terms and conditions URL (see [deal_retailer_json] for this). Where a customer is buying a Network's products from a Retailer, the Retailer's terms are more likely to be of use to the customer.
• description - A short description of the network and its primary benefits.

Nested Fields

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.

• tariff_group_id - simple integer, can be used to group similar tariffs together.
• tariff_group_description - a description of the tariff and its benefits.
• tariff_group_promo_info - should there be any promotional information to display, it will be contained here.

  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.

Nested Fields

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).

• tariff_id - can be used to link the same tariff across multiple handsets or even retailers (An O2 Big Bundle sold by O2 will have the same ID as an O2 Big Bundle sold by mobiles.co.uk)
• tariff_name - describes the tariff being sold
• tariff_type_id - See Tariff Types for valid values.
• tariff_type - This contains the type of contract being sold to the customer (also repeated in custom3).
• tariff_term - integer - the number of months the customer is tied into a contract with the network.
• tariff_term_friendly - the network's preferred wording for the contract length. In some cases Networks will legally have to refer to 1 month contracts as "30 day" (since not all months have the same number of days). Wherever a 'friendly' contract length is provided, this should be displayed on-site, with the [tariff_term] field used only for filtering/sorting/grouping. Where this field is empty, you should use the [tariff_term] field instead.
• tariff_promo_info - should there be any promotional information to display, it will be contained here.

  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.

Nested Fields

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).

mins_details

• cross_net_anytime (integer) - number of Cross-Network Anytime minutes
• cross_net_anytime_qualifier - "UK" or "Roaming See Terms". Clarifies whether any international minutes are included.
• same_net_anytime (integer) number of Same-Network minutes (if any)
• special_numbers_see_terms (integer) number of special number minutes included in the allowance (like access to 0800 or 0808 numbers).
• landline (integer) number of landline minutes included

texts_details

• cross_net_anytime (integer) number of Cross-Network Anytime texts included
• same_net_anytime (integer) number of Same-Network Anytime texts included

data_details

• wifi_mb - Amount of wifi data included in the plan in MB.

  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].

• cellular_mb - amount of data allowance included in MB
• cellular_speed - the speed at which the contract can operate.

Nested Fields

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.

• pence_per_cross_net_min - integer
• pence_per_cross_net_text - integer
• pence_per_mb - integer
• data_charge_text - string - occasionally networks don't charge per MB (sometimes a flat rate per day, for instance). Where that's the case this field will be populated and the pence_per_mb field will likely be empty.
• pence_per_voicemail_min - integer

Nested Fields

• deal_type_id - The ID of the deal type. This won't change so can be relied upon for filtering/grouping over time.
• deal_type_name - The name of the deal type.

Nested Fields

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.

  • id - The Extra Group type ID. This is consistent and can be used for grouping in your code.
  • text - The Group's text description acts as a key.

• 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.)

  • id - The Extra's Source Type ID. This is consistent and can be used for grouping in your code.
  • text - The Source Type's text description acts as a key.

• extra (Third Level) - beneath this is an array of extras and each extra's details.

  • id - The Extra's unique ID. This will never change, and if you're storing it, you could avoid re-absorbing the details of the extra next time you pull in the feed.
  • groupingId - This ID allows you to group similar Extras. In the example above, both "O2 Priority" and "O2 Tracks" have a groupingId of "M4", as they're both part of the "Entertainment freebies and discounts" Source Type. See "Interpretting the Grouping ID" for more information
  • title - a short title for the service/product being included
  • suffix - In some cases, an Extra will be time limited or there may be other exclusions that clarify important details. These will often be included in the suffix field.
  • desc - A short paragraph describing the product or service being included. We recommend having this available as a popup/mouseover or expander where it's populated (it should be in the majority of cases). The field could have escaped line breaks, so you should check for these and handle them appropriately.
  • cost - the cost of the item, if chargeable. This field will only appear where a cost exists.
  • cost_type - can be "Fixed" (a one-off payment) or "Monthly". This field will only appear where a cost exists.
  • img_url - an image URL, where available. This is currently only implemented where the source type ID is 2 ("Product"). A note about images.

Nested Fields

• name - The Retailer's trading name
• company_id - The company's unique ID.
• logo_url - The URL for the Retailer's logo to be used in comparison lists and outbound links
• terms_url - The URL for the Retailers terms and conditions of sale.

Nested Fields

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.

• upfront_inc_vat - The deal's total upfront cost including VAT
• upfront_exc_vat - The deal's total upfront cost excluding VAT (for business-customer deals)
• upfront_previous_inc_vat - Where this deal has previously been sold at another price, that price will be listed here.
• upfront_previous_exc_vat - As above but excluding VAT (for business-customer deals)
• monthly_total_inc_vat - The deal's monthly total cost (note this field will contain the sum of the phone monthly cost and contract monthly cost where these are expressed separately, as is the case with O2 Refresh products.)
• monthly_total_exc_vat - As above, but excluding VAT (for business-customer deals)
• monthly_total_previous_inc_vat - Where this deal has previously been sold at another monthly price, that price will be listed here.
• monthly_total_previous_exc_vat - As above, but excluding VAT (for business-customer deals)
• monthly_device_inc_vat - the monthly price of the device portion of the monthly cost. This will be populated only where the device is being sold separately from the tariff (e.g. Giffgaff handsets, Tesco Mobile, O2 Refresh).
• monthly_device_exc_vat - As above, but excluding VAT (for business-customer deals)
• monthly_device_term_months - in most cases the contract term for the device will be the same as for the contract, but not in all cases. In the case of giffgaff it is possible to purchase the handset over a different term from the contract (all giffgaff deals are in fact Pay-as-you-go). In all cases, this field should be checked to ensure the customer is given the correct information.
• monthly_device_final_term_inc_vat - the monthly price of the final term of the device finance contract. Currently only used by Sky Mobile, and tends to be a reduced line rental for the final few months of the device contract.
• monthly_device_final_term_exc_vat - As above, but excluding VAT (for business-customer deals)
• monthly_device_final_term_months - this is the number of months that the 'final term' lasts. If populated, this 'final term' will often feature a reduced line rental or some other changes to the way the device is financed.
• monthly_contract_inc_vat - the monthly price of the tariff portion of the monthly cost. This will be populated only where the device is being sold separately from the tariff.
• monthly_contract_exc_vat - As above, but excluding VAT (for business-customer deals)
• monthly_contract_term_months - the contract term for the tariff.
• ecpm_inc_vat - effective cost per month - the effective total monthly cost after taking into account all payments over the course of the contract and any upfront cost. Note that discounts and free gifts are not included in this calculation.
• ecpm_exc_vat - As above, but excluding VAT (for business-customer deals)
• tco_inc_vat - total cost of ownership - the total cost over the course of the contract including any upfront cost. Note that discounts and free gifts are not included in this calculation.
• tco_exc_vat - As above, but excluding VAT (for business-customer deals)

Price-rises object:

• Each item describes a future price rise in accordance with Ofcom and ASA guidance.
• date: Describes the date of the price rise in YYYY-MM-DD format.
• price_rise: Describes the amount the monthly cost will rise by on this date.
• new_airtime_cost_inc_vat: Describes the total airtime cost that will apply after the price rise. Note this value will only be populated if the product being purchased is offered on finance, where the airtime can be split out as a separate component.
• new_monthly_cost_inc_vat: Describes the total monthly cost including any finance element after the price rise has been applied. This value will always be present whether or not the offer includes finance.

Nested Fields

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.

network_discount

• nd_reduction_type_id - The type of discount being described
• nd_payment_type_id - whether the discount is applied automatically or has to be claimed by redemption
• nd_requires_promo_code (boolean) - whether this discount requires a promo code to be entered in the basket by the customer in order to be activated.
• nd_value - The value of the promotion (whether a percentage or pence value). This field can only be interpreted in the context of the reduction_type_id.
• nd_duration_in_months - the number of months that the promotional price applies
• nd_description - a description for the discount, like "Pay only 50% for 3 months (automatic)"

retailer_discount

• rd_reduction_type_id - the type of discount being described
• rd_payment_type_id - whether the discount is applied automatically or has to be claimed by redemption
• rd_requires_promo_code (boolean) whether this discount requires a promo code to be entered in the basket by the customer in order to be activated (this is very rare for retailer discounts).
• rd_value - The value of the promotion (whether a fixed price or discount). This field can only be interpreted in the context of the reduction_type_id.
• rd_duration_in_months - the number of months that the promotional price applies
• rd_description - a description for the discount, like "Pay only £8.50 for 22 months (by redemption)"

Nested Fields

Note: This field will be empty where no cashbacks are available for this deal.

• id - the unique ID for this cashback (combines type and value)
• type_id - the unique ID for the type of cashback. Valid values are 1 (redemption) and 2 (automatic)
• type_name - the text description for the above ID.
• value - the amount of cashback being offered, like "200.00"