Skip to content

DOC: Update OpenRTB mappings #108

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Eddie51D wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

DOC: Update OpenRTB mappings #108

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8066de5
Add HardwareNameVersion and HardwareNamePrefix
Eddie51D Jan 9, 2026
e76db4d
Add geo object mappings
Eddie51D Jan 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 18 additions & 5 deletions src/devicedetection/otherintegrations/openrtbmappings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

# Introduction

The RTB Project is an API specification for companies needing an open protocol for the automated trading of digital media across a broader range of platforms, devices, and advertising solutions. To aid those wishing to enhance the capture of device data, we've compiled a guide to map OpenRTB Object: Device fields to 51Degrees properties and values. The full Open RTB API Specification can be found [here](https://iabtechlab.com/wp-content/uploads/2022/04/OpenRTB-2-6_FINAL.pdf) with the Device Object specification in section 3.2.18 Device (page 28).
The RTB Project is an API specification for companies needing an open protocol for the automated trading of digital media across a broader range of platforms, devices, and advertising solutions. To aid those wishing to enhance the capture of device data, we've compiled a guide to map OpenRTB Object: Device fields to 51Degrees properties and values. The full Open RTB API Specification can be found [here](https://iabtechlab.com/wp-content/uploads/2022/04/OpenRTB-2-6_FINAL.pdf) with the Device Object specification in section 3.2.18 Device (page 28) and Geo Object specification in section 3.2.19 (page 30).

# OpenRTB API Mappings
# OpenRTB API Device Mappings

The following table lists the OpenRTB (3.2.18 Object: Device) field names, supported 51Degrees properties that contain equivalent data, alongside notes that may be helpful when mapping OpenRTB and 51Degrees values.

Expand All @@ -14,10 +14,10 @@ The following table lists the OpenRTB (3.2.18 Object: Device) field names, suppo
|sua|Structured user agent information defined by a UserAgent object (see Section 3.2.29 of the OpenRTB 2.6 spec).|Info obtained from the [User-Agent Client Hints (UA-CH) HTTP headers](@ref DeviceDetection_Features_UACH_Overview) (or equivalent NavigatorUAData JS object) sent by the browsers that support it.|ua may contain a reduced User-Agent string, thus if present, 'sua' should be considered a more accurate and complete device info. [You can also convert UA-CH values into sua information (and vice versa)](https://github.com/51Degrees/sua-uach-conversion) with our [sua and UA-CH converter](https://51degrees.github.io/sua-uach-conversion/).|
|devicetype|The general type of device. Refer to List 5.21.|[DeviceType](https://51degrees.com/developers/property-dictionary?item=Device%7CDevice)| Indicates the type of the device based on values set in other properties, such as IsMobile, IsTablet, IsSmartphone, IsSmallScreen etc.<br>See [OpenRTB Device Type Mappings](@ref DeviceDetection_OtherIntegrations_OpenRTBMappings_DeviceType) table below.|
|make|Device make (e.g., “Apple”)|[HardwareVendor](https://51degrees.com/developers/property-dictionary?item=Device%7CName)|Indicates the name of the company that manufactures the device or primarily sells it, e.g. Samsung.<br>[List of Manufactures](https://51degrees.com/developers/documentation/open-rtb-mappings/hardware-vendors).
|model|Device model (e.g., “iPhone”)|[HardwareModel](https://51degrees.com/developers/property-dictionary?item=Device%7CName)| Indicates the model name or number used primarily by the hardware vendor to identify the device, e.g.SM-T805S. When a model identifier is not available the HardwareName will be used.<br>[List of Models](https://51degrees.com/developers/documentation/open-rtb-mappings/hardware-models).|
|model|Device model (e.g., “iPhone”)|[HardwareNamePrefix](https://51degrees.com/developers/property-dictionary?item=Device%7CName)| |
|os|Device operating system (e.g., "iOS")|[PlatformName](https://51degrees.com/developers/property-dictionary?item=Operating%20System%7CName)|Indicates the name of the operating system the device is using.<br>[List of Operating Systems](https://51degrees.com/developers/documentation/open-rtb-mappings/platform-names).|
|osv|Device operating system version (e.g., "3.1.2").|[PlatformVersion](https://51degrees.com/developers/property-dictionary?item=Operating%20System%7CName)|Indicates the version or subversion of the software platform.|
|hwv|Hardware version of the device (e.g., “5S” for iPhone 5S).||This information is contained within the HardwareModel property (OpenRTB:model).|
|hwv|Hardware version of the device (e.g., “5S” for iPhone 5S).|[HardwareNameVersion](https://51degrees.com/developers/property-dictionary?item=Device%7CName)| |
|h|Physical height of the screen in pixels|[ScreenPixelsHeight](https://51degrees.com/developers/property-dictionary?item=Device%7CScreen)|Indicates the height of the device's screen in pixels. This property is not applicable for a device that does not have a screen. For devices such as tablets or TV which are predominantly used in landscape mode, the pixel height will be the smaller value compared to the pixel width.|
|w|Physical width of the screen in pixels|[ScreenPixelsWidth](https://51degrees.com/developers/property-dictionary?item=Device%7CScreen)|Indicates the width of the device's screen in pixels. This property is not applicable for a device that does not have a screen. For devices such as tablets or TV which are predominantly used in landscape mode, the pixel width will be the larger value compared to the pixel height.|
|ppi|Screen size as pixels per linear inch.|(([ScreenPixelsWidth](https://51degrees.com/developers/property-dictionary?item=Device%7CScreen) / [ScreenInchesWidth](https://51degrees.com/developers/property-dictionary?item=Device%7CScreen)) + ([ScreenPixelsHeight]( https://51degrees.com/developers/property-dictionary?item=Device%7CScreen) / [ScreenInchesHeight]( https://51degrees.com/developers/property-dictionary?item=Device%7CScreen))) / 2|Screen size as pixels per linear inch computed from screen dimensions in pixels and inches.|
Expand All @@ -36,12 +36,25 @@ This table shows the mappings between OpenRTB Device Types (5.21) and 51Degrees
|6|Connected Device|Console, EReader, SmartWatch|
|7|Set Top Box|MediaHub|

# OpenRTB API Geo Mappings

The following table lists the OpenRTB (3.2.19 Object: Geo) field names, supported 51Degrees properties that contain equivalent data, alongside notes that may be helpful when mapping OpenRTB and 51Degrees values.

|OpenRTB property|OpenRTB Description|51Degrees property|51Degrees Comments|
|---|---|---|---|
|lat|Latitude from -90.0 to +90.0, where negative is south.|[Latitude](https://51degrees.com/developers/property-dictionary?item=Location%7CCoordinates%20Accuracy)||
|lon|Longitude from -180.0 to +180.0, where negative is west.|[Longitude](https://51degrees.com/developers/property-dictionary?item=Location%7CCoordinates%20Accuracy)||
|accuracy|Estimated location accuracy in meters; recommended when lat/lon are specified and derived from a device’s location services (i.e., type = 1). Note that this is the accuracy as reported from the device. Consult OS specific documentation (e.g., Android, iOS) for exact interpretation.|[AccuracyRadiusMin](https://51degrees.com/developers/property-dictionary?item=Location%7CCoordinates%20Accuracy)|AccuracyRadiusMax is in kilometers so a conversion should be applied.|
|country|Country code using ISO-3166-1-alpha-3.|[CountryCode3](http://51degrees.com/developers/property-dictionary?item=Location%7CCountry%20Information)||
|region|Region code using ISO-3166-2; 2-letter state code if USA.|[Iso31662Lvl4 and Iso31662Lvl4SubdivisionOnly](https://51degrees.com/developers/property-dictionary?item=Location%7CRegion%20Areas)|Where Country is USA, use the SubdivisionOnly as this is the 2 letter state code. For other countries, use Iso31662Lvl4.|
|zip|ZIP or postal code.|[ZipCode](https://51degrees.com/developers/property-dictionary?item=Location%7CRegion%20Areas)||
|utcoffset|Local time as the number +/- of minutes from UTC.|[TimeZoneOffset](https://51degrees.com/developers/property-dictionary?item=Location%7CTime%20Zone)||

# Unsupported OpenRTB API Mappings
Currently, the following fields are not directly supported by 51Degrees. Unless stated otherwise, this is because the value is unique to an individual device.

|OpenRTB property|OpenRTB Description|Source|51Degrees Comments|
|---|---|---|---|
|geo|Location of the device assumed to be the user’s current location defined by a Geo object (Section 3.2.19).||[Contact Us](https://51degrees.com/contact-us)|
|dnt|Standard “Do Not Track” flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not track||This data is not captured as it is unique to a device.|
|lmt|“Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines.||This data is not captured as it is unique to a device.|
|ip|IPv4 address closest to device.|From HTTP requests.|[Contact Us](https://51degrees.com/contact-us)|
Expand Down