Phoenix API Documentation 

About 
The Phoenix API is a RESTful interface for allowing third-party applications to interrogate the
OATS database for equipment information and lubricant recommendations.

Requests & Responses 

Access to the Phoenix API is provided through a access-specific subdomain of
“phoenix.earlweb.net”.

Encoding 
Unless otherwise specified, all API requests should be encoded using UTF-8, and all responses
will be encoded using UTF-8.

Authentication 
Depending on application requirements, access to the API might require authentication in the
form of a ​token​ query parameter. If authentication is required, this parameter must be present
on every request.

Formats 
The API currently supports two response formats: XML and JSON.

The default and primary response format is XML. JSON format can be selected by either:
● appending “.json” to any request path, e.g. /browse.json, or
● including “Accept: application/json” header with the HTTP request

Compression 
The API supports gzip compression of all responses when the request includes the HTTP
header "Accept-Encoding: gzip”. Use of compression is highly recommended for all requests.

Translations 
The OATS equipment database is translated into many languages. Each API access will have
one primary language and zero or many additional languages. Requests can include a ​language
parameter to cause the response to be translated to the specified language.

Resources 
The interface consists of four top-level resources:
● /browse
● /search
● /vrm_search
● /equipment

v0.91 2019-05-14 OATS

The browse, search and vrm_search resources allow an application to identify specific
equipment. The equipment resource provides detailed information (including lubricant
recommendations) for individual equipment.

Browse Resource 
The browse resource is a hierarchical tree that partitions the large set of equipment into many
smaller sets by groups of predefined properties of equipment.

Each branch node of the tree represents a property of equipment (e.g. manufacturer) and its
children are the distinct values for that property (e.g. ‘Audi’, ‘BMW’, etc.). The leaf nodes of the
tree are the sets of equipment that match the corresponding properties of its ancestor nodes.

All child node responses also include all of the items of their ancestor nodes. The items which
are the direct ancestors of a requested node are indicated with a ‘selected’ attribute. For
example, if the root node is a list of family groups (cars, motorcycles, vans), the response for a
request to the ‘cars’ node will also include the list of family groups, with the ‘cars’ item marked
as selected.

The tree construction is flexible; the set of properties used will depend on the desired user
journey. The intention is that the application can simply follow the tree, prompting the user at
each node and traversing down the tree with the user’s selections, until a small set of equipment
is presented for the user to choose from.

The most typical case is a tree constructed from the properties: Family Group, Family and
Manufacturer.

Example: ​/browse
<response​ ​created​=​"2014-10-13T09:39:34.052Z"​>
​<index​ ​type​=​"familygroup"​ ​href​=​"/browse"​>
​<item​ ​href​=​"/browse/motorcycles"​>​Motorcycles​</item>
​<item​ ​href​=​"/browse/cars"​>C ​ ars​</item>
​<item​ ​href​=​"/browse/vans"​>V ​ ans​</item>
​<item​ ​href​=​"/browse/commercial"​>​Commercial​</item>
​<item​ ​href​=​"/browse/agricultural"​>​Agricultural​</item>
​<item​ ​href​=​"/browse/off-highway"​>​Off-Highway​</item>
​<item​ ​href​=​"/browse/industrial"​>​Industrial​</item>
​</index>
</response>

Example: /browse/cars
<response​ ​created​=​"2014-10-13T09:39:34.052Z"​>
​<index​ ​type​=​"manufacturer"​ ​href​="
​ /browse/cars"​>

v0.91 2019-05-14 OATS

 ​<parent​ ​type​=​"familygroup"​ ​href​=​"/browse"​>
​<item​ ​href​=​"/browse/motorcycles"​>​Motorcycles​</item>
​<item​ ​href​=​"/browse/cars"​ ​selected​=​"selected"​>​Cars​</item>
​<item​ ​href​=​"/browse/vans"​>​Vans​</item>
​<item​ ​href​=​"/browse/commercial"​>​Commercial​</item>
​<item​ ​href​=​"/browse/agricultural"​>​Agricultural​</item>
​<item​ ​href​=​"/browse/off-highway"​>​Off-Highway​</item>
​<item​ ​href​=​"/browse/industrial"​>​Industrial​</item>
​</parent>
​<item​ ​href​=​"/browse/cars/ac"​>​AC​</item>
​<item​ ​href​=​"/browse/cars/acura_(chi)"​>​ACURA (CHI)​</item>
​<item​ ​href​=​"/browse/cars/acura_(us)"​>​ACURA (US)​</item>
​<item​ ​href​=​"/browse/cars/alfa_romeo"​>​ALFA ROMEO​</item>
​<item​ ​href​=​"/browse/cars/alfa_romeo_(aus)"​>​ALFA ROMEO (AUS)​</item>
…
​</index>
</response>

Search Resource 
The search resource enables applications to search equipment using text keywords.

Resource URL: /search

Parameter Use Description

q required the text keywords to

search

page optional the page number of

matches to include in
response. Must be >= 1,
default is 1

page_size optional the maximum number of

matches to include in a
single response. Must be
in range 10 - 100, default is
50

<facet> optional (only for “Smart Search”) Any of the facets in the
response to a previous
search query

Example: ​/search?q=acura+1.7el
<response​ ​created​=​"2014-10-17T09:50:44.950Z"​>
​<equipment_list​ ​matches​="
​ 1"​ t
​ otal_matches​=​"1"​ ​page​=​"1"​ ​page_size​=​"50"
truncated​=​"false"​>

v0.91 2019-05-14 OATS

 ​<equipment​ ​id​=​"EFt8Pdylp"​ h ​ ref​=​"/equipment/1_7el_1_7el_EFt8Pdylp"​ ​cxid​=​"001498"
language​=​"en_GB"​ ​guid​=​"3112717418238237"​>
​<family​ ​original​=​"Cars"​>C ​ ars​</family>
​<familygroup​ ​original​=​"Cars"​>​Cars​</familygroup>
​<manufacturer>​ACURA (US)​</manufacturer>
​<manufacturer_original>​ACURA (US)​</manufacturer_original>
​<model>​1.7EL​</model>
​<model_original>​1.7EL​</model_original>
​<series​ ​original​=​"EL"​>​EL​</series>
​<displacement>​1.7​</displacement>
​<yearfrom>​2003​</yearfrom>
​<yearto>​2003​</yearto>
​<display_year>​2003​</display_year>
​<productgroup>​1.7EL​</productgroup>
​<display_name_short>​1.7EL (1.7EL)​</display_name_short>
​<fueltype​ ​original​=​"P"​>​P< ​ /fueltype>
​<display_name_long>​1.7EL (1.7EL) (P) (2003)​</display_name_long>
​</equipment>
​</equipment_list>
</response>

Facets (Smart Search only) 

If the service has “Smart Search” functionality enabled, the search response will also include
grouped attributes of the matches (“facets”) which can be presented to the end user to allow
further filtering of the matches.

Example: ​/search?q=audi+a4+2.0
<response created="2016-04-11T10:27:45.794Z">
<facets>
<facet name="series" truncated="false">
<bucket value="A3" count="3"/>
<bucket value="A4" count="520"/>
<bucket value="A4L" count="2"/>
<bucket value="A8" count="1"/>
</facet>
<facet name="manufacturer" truncated="false">
<bucket value="AUDI" count="291"/>
<bucket value="AUDI (AUS)" count="1"/>
<bucket value="AUDI (CHI)" count="28"/>
<bucket value="AUDI (US)" count="223"/>
<bucket value="AUDI (ZAR)" count="52"/>
<bucket value="AUDI-FAW (CHI)" count="2"/>
</facet>
<facet name="year" truncated="false">
<bucket value="2016" count="206"/>
<bucket value="2015" count="206"/>
<bucket value="2014" count="287"/>

v0.91 2019-05-14 OATS

 </facet>
<facet name="fueltype" truncated="false">
<bucket value="Petrol" count="298"/>
<bucket value="Diesel" count="290"/> </facet>
</facets>
<equipment_list matches="10" total_matches="597" page="1" page_size="10"
truncated="true">
<equipment .../>
</equipment_list>
</response>

Each of the facets can be used to subsequently filter the search results by sending the original
request with the facet name and bucket value as an additional query parameter. Facet names
may be used multiple times in a query to filter search results across multiple bucket values.
When multiple bucket values are given for a facet name, the search results include equipment
that matches at least one of the values.

Example: /search?q=audi+a4+2.0&year=2016&year=2017&series=A4
<response created="2016-04-11T10:32:21.815Z">
<facets>
<facet name="manufacturer" truncated="false">
<bucket value="AUDI" count="146"/>
<bucket value="AUDI (CHI)" count="21"/>
</facet>
<facet name="fueltype" truncated="false">
<bucket value="Diesel" count="90"/>
<bucket value="Petrol" count="77"/>
</facet>
</facets>
<equipment_list matches="10" total_matches="167" page="1" page_size="10"
truncated="true">
<equipment .../>
</equipment_list>
</response>

Suggestions (Smart Search only) 

If the service has “Smart Search” functionality enabled, the search response may also include
suggested edits to the query term that might provide better results.

Example: /search?q=porsh
<response created="2016-04-11T10:34:57.123Z">
<suggest_text>porsche</suggest_text>
<facets/>
<equipment_list matches="0" total_matches="0" page="1" page_size="10"
truncated="false"/>
</response>

v0.91 2019-05-14 OATS

VRM Search Resource 
The VRM Search resource allows applications to search equipment using a country-specific
vehicle registration mark.

Resource URL: /vrm_search

Parameter Use Description

q required the registration mark

vrm_type required the type of VRM index to

search

Equipment Resource 
The equipment resource provides applications with detailed equipment information, including
lubricant recommendations.

In general, applications should not construct URLs under the equipment resource. Other
resources such as browse, search and vrm_search should be queried to find equipment.

Equipment Fields 
Equipment 

Name Description Attributes

family Family name of the equipment, e.g. @original​ - name prior to

‘Cars’, Buses’ translation

familygroup Family group name of the equipment, @original​ - name prior to

e.g. ‘Retail’, ‘Industrial’ [One or Many] translation

manufacturer Original equipment manufacturer, e.g.

‘BMW’, ‘AUDI’

manufacturer_original OEM prior to translation

model Model name of equipment

model_original Model name prior to translation

series Series name of equipment [Optional @original​ - name prior to

or Many] translation

displacement Engine displacement of equipment

v0.91 2019-05-14 OATS

 [Optional or Many]

productgroup For some manufacturers this field

groups models by common series,
e.g. “1 Series” for BMW. [Optional]

yearfrom Year in which production of

equipment began. [Optional]

yearto Year in which production of

equipment ended. [Optional]

display_year Formatted year information for

presentation, e.g. “2003-2007”.
[Optional]

fueltype Primary type of fuel for the

equipment. Normally an abbreviation,
e.g. “P” for “Petrol”, “DT” for “Diesel
Turbo”. Can also be a combination of
fuel types, e.g. “P/PT“. [Optional]

display_name_short Short formatted name for

presentation consisting of model field
followed by productgroup (if present)

display_name_long Long formatted name for presentation

consisting of display_name_short
field followed by (if present) fueltype
and display_year

capacity_unit Unit of volume of application

capacities in this equipment, e.g.
“litres”, “us-gallons”

idmap Map of equipment to other data sets.

[Optional]

image Image of equipment. [Optional] @href​ - URL of image

equipment_note Contains additional information @id​ - unique identifier

relating to the equipment. [Optional or
Many] @noteindex​ - index for
presentation

app_note Contains additional information @id​ - unique identifier, also

relating to the applications of the referenced by
equipment. [Optional or Many] application/note_ref/@id

@noteindex​ - index for

presentation

@noteclass​ - one of “lube” or

v0.91 2019-05-14 OATS

 “capacity”, indicates whether
the note pertains to the
application’s lubricant
information of capacity
information

application See ​Applications​ [Optional or Many] @id​ - unique identifier

change_intervals Change intervals are the conditions @application_id​ - reference

under which the lubricant for an to the ​application/@id​ to
application should be changed. which this set of intervals
[Optional or Many] applies

@application_name​ - copy of
the corresponding
application/display_name

change_intervals/interva Each interval is either a minimum or @unit​ - interval unit, one of

l maximum unit of time or distance “miles”, “km”, “months”,
after which the lubricant should be “weeks” or “hours”
changed. [One or Many]
@display_unit​ - translated
interval unit

@display_name​ - presentable
interval name, including the
@display_unit​ and one of
“min” or “max”

Applications 
Applications represent different parts of the equipment that a product can be applied to.

Name Description Attributes

name Name of application

app_type Type of application, possibly translated

app_type_original Type of application. One of the

following:
● Brake and Clutch
● Coolant
● Differential
● Engine
● Greases
● Hydraulic Fluids
● Other
● Steering
● Transmission

v0.91 2019-05-14 OATS

 Note: additional types may be added in
the future.

note_ref References the ​app_note​ fields that @id​ - the id of the

apply to the application. referenced ​app_note

@noteclass​ - the type of

the note, either “lube” or
“capacity”

@noteindex​ - index for

presentation of the
referenced note

display_lube_note_refs Formatted list of lubricant note indexes

(from ​note_ref​ fields with
@noteclass=”lube”)​ . [Optional]

display_capacity_note_ref Formatted list of capacity note indexes

s (from ​note_ref​ fields with
@noteclass=”capacity”)​ . [Optional]

product Product recommendations for the @cid​ - id of the branding

application. [Optional or Many] channel for the product
match. Normally every
product will have the
same channel. [Optional]

@tier​ - id of the branding

channel’s tier for the
product match. Normally
an integer in the range
[1,2,3], where 1 is the
highest priority and 3 is
the lowest. [Optional]

@channel_name​ - name
of the branding channel.
Normally the same for
every product and not
presented to the end
user. [Optional]

@tier_name​ - name of
the branding channel’s
tier. Should be displayed
with the product name
when there is more than
one product.

@type​ - product type,

either “p” for a normal
product, or “pp” for a

v0.91 2019-05-14 OATS

 “pseudo product” (i.e. no
suitable product is
available, ​product/name
will contain further
information for the end
user). [Optional]

@nonbrandable​ - value of
“true” indicates that the
application cannot
reasonably have any
product applied to it. The
product/name​ field will
contain a message
explaining why (e.g.
‘Filled For Life’).
[Optional]

product/name Name of product

product/external_id Product identifier provided by client

during branding process. [Optional]

product/resource Additional resources associated with @type​ - type of the

product, e.g. product packshot or link to resource (e.g. ‘packshot’,
technical data sheet. [Optional or Many] ‘tds’)

@href​ - URL of resource

fueltype Type of fuel for this application.

Normally an abbreviation, e.g. “P” for
“Petrol”, “DT” for “Diesel Turbo”. Can
also be a combination of fuel types, e.g.
“P/PT“. [Optional]

option Additional information to distinguish

multiple applications of the same type,
or where equipment might have a
choice of applications (e.g. “5-Speed”
or “6-Speed” options for a manual
transmission). [Optional]

mixratio Indicates the product should be mixed

with some other fluid using the specified
ratio. Typically used for anti-freeze
coolants (e.g. “50%”). [Optional]

display_name Formatted name for presentation

consisting of ​name​ field followed by (if
present) ​fueltype,​ ​option​ and m
​ ixratio​.
May also include ​display_coption​ if
configured.

v0.91 2019-05-14 OATS

 capacity Volume of product required for this @type​ - capacity type,
application. either “choice” (default) or
“range”.

“choice” capacities have

one or more ​option
children, each
representing a valid
capacity. Most choice
capacities have one
option,​ but some have

“range” capacities have

exactly one ​min​ and one
max​ children.

capacity/option For ​capacity​ fields with ​@type=“choice”​,

each ​option​ is a valid capacity. [Optional
or Many]

capacity/min For ​capacity​ fields with ​@type=”range”

contains the minimum capacity range.
[Optional]

capacity/max For ​capacity​ fields with ​@type=”range”

contains the maximum capacity range.
[Optional]

display_capacity Formatted capacity information for

presentation. Contains all of the
information from the ​capacity​ field and
its children in a more presentable
format. [Optional]

Application “coption” (Chatham data sources only) 

If the service is configured to use a Chatham equipment then there may be multiple applications
with the same name within a single equipment response. These applications are distinguished
by the coption and display_option fields of each application.

An example of the logical a front-end application might use to present the coptions:
● Group applications together by the name field.
● For each group with more than one application, present a choice all of the
display_coption fields for the user.
● When the user chooses a particular display_coption, show the details for the
corresponding application.

An alternative presentation might be:

v0.91 2019-05-14 OATS

 ● Present all of the applications in order
● Where the application name is shown, also show the display_coption field if present

Name Description

display_coption Formatted text presentation of the coption.

coption Container element for describing the variables of the

application that distinguish it from other applications of the
same name.

coption/conjunction Group for a set of variables. If there are multiple conjunctions

within a single coption then they represent logical OR choices.

coption/conjunction/bind Container for a specific variable and value combination that

this conjunction applies to. If there are multiple binds, they
must all be true for the conjunction to apply.

coption/conjunction/bind/var The variable in question, typically a property of the equipment.

coption/conjunction/bind/value The value of the variable for that this particular conjunction
applies to.

Example 
<application>
<name>Engine</name>
<display_coption>Long Drain</display_coption>
<coption>
<conjunction>
<bind>
<var>qg</var>
<value>QG1</value>
</bind>
</conjunction>
</coption>
...
</application>
<application>
<name>Engine</name>
<display_coption>Short Drain</display_coption>
<coption>
<conjunction>
<bind>
<var>qg</var>
<value>QG0/2</value>
</bind>
</conjunction>

v0.91 2019-05-14 OATS

 </coption>
...
</application>

Application Index (Chatham data sources only) 

If the service is configured to use a Chatham equipment data source, it may optionally be
configured to provide an application index to help front-end applications to present questions to
the end user to select from a choice of recommendations.

The application index contains one child ​app_ref​ for each set of related applications, e.g. one
app_ref​ for all “Engine” applications, a second ​app_ref​ for all “Differential” applications.

Each ​app_ref​ contains a tree, the branch nodes of which are choices, and the leaf nodes are
each a reference to a specific application.

The tree may be of any depth, but in the vast majority of cases the root node will be an
application reference (i.e. no choices), then the majority of the remainder will be depth of 2 (i.e.
one choice).

Name Description

app_ref Container for a set of related applications

app_ref/name Name of application

app_ref/display_name Formatted name for presentation consisting of

name​ field followed by (if present) ​fueltype,​ o
​ ption
and ​mixratio

app_ref/fueltype Type of fuel for this application.

app_ref/option Additional information to distinguish multiple

applications of the same type, or where equipment
might have a choice of applications (e.g.
“5-Speed” or “6-Speed” options for a manual
transmission). [Optional]

app_ref/application_ids Reference to an application in this set [One or

Many]

app_ref/decision_tree Nested tree representation of choices to resolve a

single application from the set.

The decision tree consists of nodes, each if which has a ​type​ of either “choice” (indicating a
branch) or “application” (indicating a leaf).

v0.91 2019-05-14 OATS

Branch nodes consist of:

Name Description

type “choice” for branch nodes

choice Top-level container for the children of the branch

choice/var Internal variable name

choice/display_name User-friendly label for the variable name

choice/option Child options of the branch. Each option is itself a

node and may have further children. [Many]

choice/option/value Internal value for variable

choice/option/display_value User-friendly label for the value

choice/option/type Type of the option node, either “choice” (indicating

another branch) or “application” (indicating a leaf).

Leaf nodes consist of:

Name Description

type “application” for leaf nodes

application_id Reference to the application that corresponds to

the choices made through the decision tree.

Example 
<application_index>
<app_ref>
<name>Engine</name>
<fueltype>PT</fueltype>
<option>CREC</option>
<display_name>Engine (PT) (CREC)</display_name>
<application_ids>1</application_ids>
<application_ids>2</application_ids>
<decision_tree>
<type>choice</type>
<choice>
<var>qg</var>
<display_name>Service regime</display_name>
<option>
<value>QG0/2</value>
<display_value>Short Drain</display_value>
v0.91 2019-05-14 OATS
 <type>application</type>
<application_id>1</application_id>
</option>
<option>
<value>QG1</value>
<display_value>Long Drain</display_value>
<type>application</type>
<application_id>2</application_id>
</option>
</choice>
</decision_tree>
</app_ref>
</application_index>

Document History 
2014-10-17 
● Add paragraph explaining the browse resource responses including items from ancestor
nodes, plus example.
● Add information on search resource response pagination.
● Add equipment/application/product/external_id information.

2014-12-16 
● Update descriptions of equipment/familygroup and equipment/series fields to include
cardinality.
● Add equipment/displacement information.

2016-04-11 
● Add descriptions of “Smart Search” features, Facets and Suggestions, to search
resource.

2017-10-11 
● Add subsection to “Equipment Fields” describing the new coption and display_option
application fields.

2018-04-04 
● Add subsection to “Equipment Fields” describing the new application index section for
Chatham data sources.

2018-09-12 
● Corrections to field descriptions. In particular, fix the cardinality of application product
field.

2018-10-17 
v0.91 2019-05-14 OATS
 ● Add explanation on filtering multiple bucket values in smart search.

2019-05-14 
● Add “app_type” and “app_type_original” definitions to equipment application description.

v0.91 2019-05-14 OATS