Enhanced telco data feeds overview

Special feeds for single offers from telco advertisers

About the enhanced data feeds for mobile telecoms sector

Awin has a solution to provide enhanced data feeds for the mobile telecoms sector.

Sitting within our create-a-feed technology, our enhanced telecoms data feeds bring an unmatched level of product data to partners working in this sector. The telco specific feeds set the standard for data delivered to mobile telecoms partners, and will include richer handset and tariff information than has ever been available via the channel before, in a standardized format that makes it simple to access and implement.

Some of the improvements available from Awin’s enhanced telecoms feeds, include:

• Detailed product descriptions, including all brand attributes and wraparound services

• Standardized, high-quality images

• Full and standardized device attributes

• All service attributes, including service allowances and coverage

• Device condition, such as new/refurbished

The mobile telecoms sector is one of the biggest and most important for product and price comparison. Providing the richest and most accurate product data is a vitally important and a frequently forgotten requirement within our industry.

We offer detailed developer documentation about the Awin enhanced telco feeds.

It is recommended as advertiser to adjust the feed name for better recognizability on the partner’s site. For this please replace the feed name (e.g. Default) with Enhanced Telco Feed.

Important notes

Field names suffixed with non-null cannot be null/empty. Your import code can rely on these values always existing and you should report an issue to Awin if you ever encounter an empty value.

Note

A value of 0 could have a specific meaning.

Anyone planning to use the JSON fields should not need to absorb any of the fields described in Standard fields. The only exceptions are merchant_product_id, merchant_deep_link and last_updated so these should always be checked along with the fields described in JSON telco fields when downloading from create-a-feed as partner. All others can remain un-checked.

Field names in the standard schema are in many cases slightly misleading as the schema has to cope with multiple verticals. It’s important therefore to read this documentation in order to understand the proper function of each field in the context of the telco vertical. JSON fields on the other hand are telco-specific and are more appropriately named.

All telco fields are available in the same schema (group of check boxes) in create-a-feed, but they’re described here separately as JSON Telco fields and Standard fields as their intended use is different.

In general all products are better described, and in more detail in the JSON telco fields.

Implementation tips

These implementation tips can be used in conjunction with wireframes (PAYG - pay as you go and PAYM - pay monthly) that demonstrate the relative importance of various data elements through the use of color and positioning.

Grouping and filtering devices

Should you wish to focus purely on the hardware, the merchant_category (standard) or device_product_json (JSON) fields provide basic product type categorization, with the JSON fields in general providing a more reliable ID-based approach.

In many cases however, it’s likely that you will want to also filter based on the type of contract (pay as you go, mobile broadband, sim only, etc.), as well as deal type (consumer, existing customer, upgrade, business, etc.) linked to the device in order to ensure the customer doesn’t end up looking at a device only available on a type of contract they aren’t interested in.

For deal type, check out the product_type or deal_type_json fields, and details of the contract type are available in custom3 and tariff_details_json.

Sorting and filtering discounts

Discounts (whether network or retailer discounts) are represented identically aside from field naming. This means that both types of discount can be stored internally in the same table, with just a marker denoting whether the discount is a retailer or network discount. This should make filtering far easier.

The nd_reduction_type_id and rd_reduction_type_id fields can be used to group deals by the type of discount being offered, or perhaps more usefully, the fields can be used in combination with the value and duration_in_months fields to calculate the total discount available and use this derived value as a means of sorting the results (or comparing against cashbacks - see Grouping and filtering cashbacks below.

Using the *_payment_type_id field, developers can group deals according to whether or not the customer is required to redeem the discount, or whether it is automatically applied. In many cases customers will prefer to opt for an automatically applied discount.

Grouping and filtering cashbacks

Cashbacks are really just a simpler type of discount where the amount of discount is expressed as a total discount available. This means cashbacks can be compared directly against discounts in two ways:

• Compare cashback value with the derived total discount mentioned in Sorting and filtering discounts above.

• Compare claim method (automatic / redemption) in the cashback type_id field against the claim method stored in a discount’s *_payment_type_id field.

Understanding pricing

Many will be used to the idea of pricing in the telco vertical being split into an upfront cost (a deposit of sorts on the hardware, assuming we aren’t dealing with a SIM-only deal) and a monthly cost that covers the service/allowances being purchased but also subsidises the cost of the device.

While the above approach still exists, there are now more complex pricing structures being adopted that not only have a bearing on the data now made available via data feeds but also on how pricing is displayed on the web. In many cases there can be legal requirements that have to be met (such as displaying information about RPI-linked price increases or credit agreements) and pricing is now increasingly represented as one price for the service, and another for the handset or device. Additionally the contract term for the device and service can be different (so for instance Giffgaff offer 30 day top-ups, and hire purchase agreements for the device of up to 24 months)

When should I use ex. VAT pricing?

If the deal is a business deal (product_type or deal_type_json fields), then you should use ex. VAT pricing wherever possible. It is acceptable to use inc. VAT pricing in circumstances where consumer and business deals are being compared but you should indicate clearly that the customer will be charged ex. VAT when it comes to payment.

How will I know when to show separate monthly prices for devices and tariff?

For comparison / sorting / filtering purposes you can safely just use the upfront_inc_vat / upfront_exc_vat and monthly_total_inc_vat / monthly_total_exc_vat fields. It's only when it comes to displaying pricing for the deals in question that you need to worry about any split.

Identifying a deal where the price has been split is straightforward - if monthly_device_inc_vat / monthly_device_exc_vat is populated, then we’re dealing with a split-pricing deal. Remember that the contract length for the device (monthly_device_term_months) can be different from the contract length for the service/tariff (monthly_contract_term_months), so you’ll need to ensure these are properly represented on the page along with the legal text if populated.

I'm not using the JSON fields. How can I implement split-pricing?

This is currently unsupported. Split pricing information is only available here. Even if you aren’t able to use JSON natively in your code, it may be possible to extract the required values using some simple regular expressions, though the exact method will depend on your programming language of choice.

Displaying tariff information

Note that this section assumes the use of JSON fields. When displaying a deal, the following should be considered:

• The tariff_group provides a tariff description, which can help to 'position' the tariff.

• If you want to show customers similar tariffs, you can use the tariff_group_id to link similar tariffs from the same network together.

• Promotional information about the deal can be held in up to three different fields (and is concatenated in the ‘standard schema’ field promotional_text). The information held in these fields is free text, is supplied by merchants and networks in order to better describe the deal being sold and so should be passed through unaltered.

  • tariff_group_promo_info - Contains information that applies to all tariffs grouped within.

  • tariff_promo_info - Contains information that applies to this tariff and all deals linked to it.

  • deal_promo_info - Contains information specific to this deal.

• Outside of the usual basic details that customers expect to find on comparison sites or in tariff tables, making use of (for instance) deal_extras_json and tariff_group_details_json - tariff_group_description to list the benefits associated with any given deal can be a powerful selling tool. Space constraints are likely to mean that benefits should be revealed using progressive disclosure techniques, and we recommend priority be given to information in the following order:

  • tariff_allowances_json

  • deal_discounts_json

  • deal_cashback_json

  • promotional information fields - tariff_group_details_json - tariff_group_promo_info, tariff_details_json - tariff_promo_info, deal_promo_info

  • deal_extras_json

  • tariff_group_details_json - tariff_group_description

  • network_details_json

  • tariff_out_of_plan_charges_json

  • deal_retailer_json

About images

We attempt to ensure that images are provided in all cases however there are some situations beyond our control (for instance early product pre-orders) that mean images won’t always be available. Where that’s the case we will always provide a placeholder image so your import code won’t throw errors and your web page won’t contain any broken image links. As soon as we are able to get hold of the relevant image, the feed will be updated to include it.

In total there are six styles of image available, listed below:

• merchant_image_url - white background, 400x400 pixels, PNG

• aw_image_url - white background, 200x200 pixels, JPEG

• merchant_thumb_url - white background, 150x150 pixels, PNG

• aw_thumb_url - white background, 70x70 pixels, JPEG

• large_image - transparent background, 400x400 pixels, PNG

• alternate_image - transparent background, 150x150 pixels, PNG

Note

The large_image and alternate_image data is repeated in the device_images_json field.

Handling feed updates efficiently (JSON only)

Since the JSON fields are structured and include IDs wherever possible, we can rely on them to efficiently update the feed whenever it is imported. Rather than overwriting everything in your local database each time you import a row of the CSV you can check each ID just once, and then ignore any further occurrences of it in the feed.

For a super-quick import you can even just check some of the fields as described below, though you risk not picking up on corrections to previously faulty data (human errors will always happen). If you do want to use this approach we recommend that you perform a more complete update once every couple of days or so.

Bare minimum field value updates

During each feed import run, assuming the IDs (and previously imported data) for the below already exist in your database:

• merchant_product_id - Since this is unique to a specific combination of product, service and any extras, you need only check:

  • deal_cost

  • deal_promo_info

• tariff_group_details_json - Check the first occurrence of each tariff_group_id for the following:

  • tariff_group_description

  • tariff_group_promo_info

• tariff_details_json - Check the first occurrence of each tariff_id for the following:

  • tariff_name

  • tariff_promo_info

• device_product_json - Can be skipped entirely if the product_id and related data have previously been collected.

• device_product_version_json - As above.

• device_product_edition_json - As above. Additionally, the following can be skipped, as they relate to the product edition and will change very rarely:

  • device_full_name

  • device_description

  • device_images_json

  • device_features_json

  • device_specifications_json

• network_details_json - Can be skipped entirely if the company_id (in the context of a network, because details might be less complete when the company is presented as a retailer) and related data have previously been collected.

• deal_retailer_json - Can be skipped entirely if the company_id and related data have previously been collected (whether as a network or a retailer).

• deal_discounts_json - Can be skipped entirely if the nd_id or rd_id have been encountered previously (not just in this feed run, in any).

• deal_cashback_json - Can be skipped entirely if the id has been encountered previously (in any feed run).

Skipping fields based on network_details_json

Where the network_details_json - company_id is 76, we’re dealing with a product that comes without a contract. Therefore we can skip the following fields, which will be unused in this context:

• tariff_group_details_json

• tariff_details_json

• tariff_allowances_json

• tariff_out_of_plan_charges_json

• deal_legal_info

• deal_extras_json

• deal_discounts_json

• deal_cashback_json

Specifications and features availability

In all cases where the product is a Mobile Phone (device_product_json - product_type_id = 1), all of the fields mentioned below should be populated.

• device_features_json - and all sub-fields

• device_specifications_json - and all sub-fields

• operating_system

• storage_size

• colour

• dimensions

• specifications - and all sub-fields

Where the product type is not a Mobile Phone, you should check each field carefully for a value without assuming they will always be available.

Valid values reference guide

The following indexes demonstrate what values you can expect in the relevant fields based on the product_type and contract_type.

Note

These are the valid values as of the time of writing this documentation. If you received a value that isn’t listed on this webpage, it might not reflect on this document yet. Please contact us and provide as much information as possible.

Deal type

The deal type lookup table below lists all the IDs and their meanings. The IDs tend to be used in JSON fields, while the text values appear in the simpler CSV fields.

Not all values are used across all feeds. Whether a value is used depends on the scope of products each merchant ranges and the demographics they target with those deals.

• 0 - Consumer - Default. Note that Consumer deals don’t necessarily exclude business customers, but they will be billed inclusive of VAT.

• 1 - Consumer Upgrade - As above, but limited to customers who already have a qualifying product from the network this deal applies to. The most obvious example is a customer who already has an O2 mobile phone contract, and would like to buy another O2 contract, but upgrade their handset at the same time, keeping their number.

• 2 - Consumer Existing Customer - Unlike above, the customer might have a non-mobile contract (like broadband or TV). These ‘existing customer’ deals provide favourable pricing for customers who already purchase some other service from the network in question. Current examples include Virgin Mobile (who sell discounted mobile products to their existing broadband/TV customers) and TalkTalk whose mobile products are only available to their existing customers.

• 3 - Business - Available to business customers only. Prices should be represented as ex. VAT wherever possible (or clearly marked as including VAT).

• 4 - Recycling - New - Available to business customers only. Prices should be represented as ex. VAT wherever possible (or clearly marked as including VAT).

• 5 - Recycling - Working - Available to business customers only. Prices should be represented as ex. VAT wherever possible (or clearly marked as including VAT).

• 6 - Recycling - Broken - Available to business customers only. Prices should be represented as ex. VAT wherever possible (or clearly marked as including VAT).

• 7 - Consumer - Affiliate Price - Special affiliate price. You will also see exclusive in the keywords field, and Consumer in the product_type field.

• 8 - Consumer Existing Customer - Affiliate Price - As above, but for existing customers. You will also see exclusive in the keywords field, and Consumer Existing Customer in the product_type field.

• 9 - Consumer - Publisher Exclusive - This will only appear if you have agreed an exclusive with the advertiser. You will also see exclusive in the keywords field, and Consumer in the product_type field.

• 10 - Consumer Existing Customer - Publisher Exclusive - As above but for existing customers. You will also see exclusive in the keywords field, and Consumer Existing Customer in the product_type field.

• 11 - Dummy Deal - These types of deals should never be encountered. If you are receiving one, please contact us.

• 12 - Trade-in - This price is dependent on the customer trading in an eligible device.

Product types

The product type relates to the deal device as well as any extras that may be included in the deal and referenced from deal_extras_json. Each product type has an ID which would usually be referenced in the json fields with the text value. Simpler CSV fields will use just the text value.

Not all values are used across all feeds. Whether a value is used depends on the scope of products each merchant ranges and the demographics they target with those deals.

• 1 - Mobile Phone

• 2 - SIM Card

• 3 - Tablet

• 4 - USB Modem

• 5 - Laptop

• 6 - Mobile Wi-Fi

• 7 - Game Console

• 8 - Smartwatch

• 9 - Television

• 10 - Wearable

• 11 - Case

• 12 - Headphones

• 13 - Software

• 14 - Camera

• 15 - Media Streamers & Players

• 16 - Charging, Docks & Stands

• 17 - Personal Grooming

• 18 - Input Devices

• 19 - Toys & Gadgets

• 20 - Speakers

• 21 - VR Headsets

• 22 - Smart Home

• 23 - Multiplay Device

• 24 - Router

• 25 - TV Box

• 26 - Output Devices

• 27 - Portable Memory

• 28 - GPS Tracker

• 29 - Personal Transportation

• 30 - Landline Device

• 31 - Fitness Accessory

Tariff type

This is the type of contract being sold to the customer.

Tariff_types 12, 13, 14, 15, 16 and 17 are reserved for TV, landline and broadband feeds, and won’t ever be encountered in a mobile phone feed

Not all values are used across all feeds. Whether a value is used depends on the scope of products each merchant ranges.

• 1 - Mobile Broadband Contract - A contract that usually only includes a data allowance.

• 2 - Mobile Broadband Pre-pay - A pay-as-you-go deal with no contractual commitment intended for use with MBB devices.

• 4 - Phone Contract - A contract that usually includes minutes, texts and data.

• 5 - Phone Pre-pay - A pay-as-you-go deal with no contractual commitment intended for use with phones.

• 11 - SIM/Contract Free

• 12 - Broadband

• 13 - Landline

• 14 - TV

• 15 - Broadband and Landline

• 16 - TV, Broadband and Landline

• 17 - TV, Mobile, Broadband and Landline

Extra group types

Used as part of deal_extras_json, the extra group type provides a detailed categorization for any included extras. This should allow your software to break out any extras that you would like to provide special handling for (e.g. physical free gifts, top-ups).

An ID of 1 means the source type is an allowance (data/texts/minutes), and an ID of 2 means the source type is a product (most usually applies to free gifts). An ID that begins 255 is 'something else' - this is used for most other 'soft' benefits like additional services or rewards.

• 1 - "Allowance" - A minutes, texts or data allowance

• 2 - "Product" - A physical product

• 255-1 - Gift Voucher

• 255-2 - Top-ups

• 255-3 - Service Attributes

• 255-4 - Inclusive Entertainment

• 255-5 - Enhanced customer service

• 255-7 - Reward Points

• 255-11 - Roaming Service

• 255-16 - Trade-in Service

• 255-18 - Device backup

• 255-19 - Commitments and Guarantees

• 255-25 - Free or discounted software

• 255-27 - VOIP Services

• 255-28 - Separate Call & Device Contract

• 255-29 - Discounted Second Line

• 255-30 - Capping Service

• 255-31 - Data Speed

• 255-32 - Flexible Plans

• 255-33 - Hotspot/Tethering Service

• 255-34 - Inclusive Social Media

• 255-35 - Referral Scheme

• 255-36 - Sharing Service

• 255-37 - Savings

• 255-38 - Extra Data

• 255-39 - Delivery Service

• 255-1039 - Rollover Service

• 255-1040 - Wi-Fi Access

• 255-1041 - Self-service App

• 255-1042 - Anti-virus and anti-malware

• 255-1043 - Insurance

• 255-1044 - Bill Credit

Extra source types

Used as part of deal_extras_json, the extra source type provides a broad categorization for any included extras. This might allow you to apply further logic to your categorization code.

• 1 - Free Gifts - Contains details of any physical goods included as part of the deal, for instance free televisions, games consoles or boxed software that the customer owns without limitation. Time-limited software (like Free Evernote Premium for a year) is considered a free service, and included in Inclusive Services (below) instead.

• 2 - Inclusive Services - Contains details of services or allowances that are included as part of the deal at no extra cost to the customer. Current examples include Extra 750MB Wifi for the first 3 months, BlackBerry services, Tethering, and 6 months free Netflix.

• 3 - Discounts & Loyalty - Contains details of rewards or discounts linked (perhaps loosely) to customer loyalty. Examples include Tesco Clubcard points, charity donations on the customer’s behalf or trade-in discounts for existing customers.

• 4 - Comes with (chargeable) - Contains details of additional products or services that are a mandatory part of the overall deal but for which the price charged isn’t reflected in the upfront price. In all current examples this is limited to top-ups for PAYG devices but there may well be different types in future. This is arguably a hangover from the days when a phone could be purchased (from a bricks-and-mortar shop) with a larger top-up if required and so the price of the top-up was excluded from the advertised price, but this doesn’t actually happen on the web. You might consider just rolling the cost of the top-up into the upfront price, though this risks making the deal look less attractive.

• 6 - Bundled products - Contains details of any bundled products or services that make up the deal. The most obvious current examples are EE’s Sharer deals that contain two products and two tariffs intended to be shared amongst the devices.

Allowance types

Where the extra_group_type = 1, the allowance_type allows your code to understand whether you are dealing for example with a data allowance vs. a texts allowance that is being bundled into the deal.

• 1 - Talk Time

• 2 - Texts

• 3 - Data

• 4 - Channels

Discount types

The discount types combined allow your code to understand the nature of the discount being offered and to calculate your own representation of the discount (you may have a preference for £ reduction or % for example). Alternatively discounts are also described in less detail in the simpler CSV fields.

• 1 - Fixed price (for instance, pay only £20/month - the _value field will contain the monthly price in pence)

• 2 - Fixed reduction (for instance, £20 off per month - the _value field will contain the monthly discount in pence)

• 4 - Pay percentage (for instance, pay only 50% each month - the _value field will contain the percentage of the monthly price to be paid by the customer)

• 8 - Percentage reduction (for instance, 25% off each month - the _value field will contain the percentage discount)

Payment types (used in the above nd_payment_type_id and rd_payment_type_id fields):

• 32 - By redemption

• 64 - Automatic payment

Connectivity type

Describes the fastest 'speed' at which the contract will allow the customer to access data services

• 3G

• 4G

• 4G Double Speed

• 5G

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.

• Black

• Blue

• Brown

• Gold

• Green

• Grey

• Orange

• Pink

• Purple

• Red

• Rose Gold

• Silver

• White

• Yellow