Skip to main content

Formatting Key-Value Files

Key-value files are best suited for files with only one identifier field (this will typically be data tied to a device identifier such as a cookie, or PII-based data tied only to a single email address or phone number).

Note

  • For data that includes multiple identifiers: Key-value files can be used but this type of data are often best delivered as a column-based file. See "Formatting Column-Based Files" for more information.

  • Data from EMEA countries and Australia: Data can only be accepted in a column-based file format. Key-value files are not allowed for EMEA and Australian data. For more information, see "Creating Data Files for EMEA Countries".

Formatting Guidelines for Key-Value Files

Follow the guidelines listed below for the best results, and see "Examples of Key-Value Segment Data Files" for examples of key-value files.

  • When there is a single identifier, it should be the first field of each row and does not need to include a key: <identifier>,k1=v1,k2=v2 (not ID=<identifier>,k1=v1,k2=v2)

  • When there are multiple identifiers, all identifiers should be in key-value format: email=<email address>,phone=<phone number>,k1=v1,k2=v2

    Caution

    Separate keys and values with an equals sign (=). Contact your LiveRamp representative if this will be a problem for you.

  • Separate the identifier and each key-value pairwith one of the allowed delimiters.

  • Keys should be unique per row. That is, do not include something like <identifier>,k1=v1,k1=v2. In the case of multi-valued data, make a new row tied to the identifier for each value tied to the same key.

  • If using quotation marks, do not put the equals sign or delimiters inside the quotation marks. Each key and value should be individually double-quoted: "<identifier>","k1"="v1","k2"="v2" (not "<identifier>","k1=v1","k2=v2"). See "Formatting Guidelines for All Files" for more information.

  • If there is no value for a given key for an identifier, do not include that key in that row. That is, do not include something like "k1”="”.

  • Include every possible key in the first row (optional, but recommended). This allows us to quickly detect every key that might show up in the file and reduces the chance of error. This row can be all "dummy" data: a placeholder identifier and all keys set to equal "1."

Examples of Key-Value Segment Data Files

Key-value files are often best suited for files with only one identifier field (this will typically be data tied to a device identifier such as cookies, or PII-based data tied only to a single email address or phone number). See "Formatting Key-Value Files" for more information.

Single Identifier Key-Value File Example

Simple key-value file with a single identifier in the first column, suitable for device-based data tied to a cookie, mobile device ID, or similar. PII-based data tied to a single email or phone number could also be formatted this way. Not all rows have values for every key, so those keys are not included in those rows.

File Example Good No Quotes Key Value-_vg.jpg

Download the Key-Value File Single Identifier Example file template

Single Identifier Key-Value File Enclosed with Quotation Marks Example

Similar to the above example, but with a new field, "PreviousCity", that contains a comma and so therefore keys and values are enclosed with quotation marks. Note that the equals signs and delimiter commas remain outside the quotation marks.

File Example Good Quotes Key Value-paA.jpg

Download the Key-Value File With Quotation Marks Example file template

Common Key-Value File Errors Example

This file contains a number of typical file formatting errors:

File Example Bad Key Value-rsY.jpg

  1. "San Francisco, CA" is not enclosed in quotation marks, so the value for "PreviousCity" will be interpreted as "San Francisco."

  2. The identifier appears to have been hashed, while the identifiers in other columns are plaintext.

  3. All the key-value pairs including the equals sign are completely enclosed by quotation marks rather than each individual key and value enquoted separately.

  4. The key "Under25" is set to equal no value and should have not been included at all.

  5. Colons rather than equals signs have been used to separate keys and values.

Download the Key-Value File Errors Example File

Note

See "Uploading Data" for an overview of the file creation and formatting process.

In this section:

A type of data file where each row contains key/value pairs in the form of "key=value" (for example, "gender=female").

A category of identifiers where the identifiers are based on digital devices (for example, cookie IDs or mobile device IDs).

A packet of data sent by an Internet server to a browser, which is returned by the browser each time it subsequently accesses the same server and used to identify the user or track their access to the server.

Personally identifiable information (such as name and postal, phone number, or email address) which, on its own or when combined with some other data, can be used to identify an individual.

A type of file where every row has the same number of fields and the field names are contained in a header row, as opposed to a key/value file.

Data that are used to identify something, such as a person, mobile device, computer browser, or household.

In a key-value file, the category for a particular value (for example, a key of "gender"). Similar to a header in a column-based file.

A character (such as a comma or pipe) that acts as a separator between two values in a data file.

Within a column of segment data in a data file, the entry for a given record that indicates a trait or attribute value, such as "BMW" in a field named "Car_Owned." A group of users with a specific field-value pairing creates a segment.