Introduction

Overview

You can think of UVDB and GAPC as two separate structures - UVDB for organizing vehicles, GAPC for organizing parts. GAPC parts link to UVDB vehicle definitions, and configs, to provide accurate fitment.

UVDB

UVDB simply provides a good structure for linking to parts. When creating software, marketplaces, or even internal systems, this is a good scalable foundation. There are a few key aspects of UVDB.

UVDB - A deeper explanation

GAPC

GAPC is a global parts catalogue. It stores and structures information relating to parts in a well-defined, scalable way. Global translations, and multi-continent distribution is available via the "i18n" resource.

GAPC - A deeper explanation

Fitment

There are two types of fitment

There are two types of fitment, depending on what you want to do, how accurate you want your fitment, how simple your integration is, and which 3rd parties/marketplaces you want to interact with.

Fitment - Defined vs config fitment

Connecting it all together

The following diagram summarizes how UVDB and GAPC relate(Use Ctrl + Scroll, or the "+" and "-" in the bottom right to zoom in)

Usage Overview

The process to get setup is as follows

  1. Talk to us. Confirm your usage is applicable for UVDB/GAPC (read the information below + documentation and let us know any questions).
  2. If you don't have your API Keys yet, you can set up a trial account via your PartsPal account to test. Follow these instructions.
  3. Onboard you as a customer with the plan that works for you.

Overview

GAPC is the Global Auto Parts Catalog. This is a database of both OEM, OE and Aftermarket part information including vehicle compatibility (linking with UVDB) and cross-referenced / interchangeable part numbers. The database includes 45 million+ parts, GAPC does not provide pricing or stock information, this can be added from a supplier.

UVDB is the Universal Vehicle Database. This is a database of vehicle information including up to 400 attributes per vehicle (not all queriable via the API). The database will contain a separate vehicle list utilizing localized nomenclature and vehicle referencing for different regions.

Fully supported regions include:

  • Europe (including the UK)
  • North America

Partially supported regions include:

  • South America
  • Australasia
  • Middle East

The API is GraphQL which is a query language for APIs. This is modern, easy to use and includes general documentation within the API.

You may also consider using our software, PartsPal, to bring auto parts data onto a website.

How to test the Partly API

Authentication

Authentication is done via shared keys - to generate your API keys

  1. Login to PartsPal (or create an account from: https://admin.parts-pal.com)
  2. Go to "Settings" -> "Developer Options" -> "API Keys" then click "Generate Keys"
  3. Click "Copy key"

You now have your permanent API key for authenticating your app.

Testing environment

To begin testing:

  1. Go to https://api.parts-pal.com/node-api/graphql
  2. Click http header button at the bottom left of the screen
  3. Paste the following code in http header panel, but use your own public key:


{% c-block language="Javascript" %}
{    "x-api-key":"paste public key here"}
{% c-block-end %}

Example query

Finally, to search for your first part add the query below, and click "Play" button.

{% c-block language="GraphQL" %}
{
 gapc {  
  parts(q: "0 190 350 049") {
     items {
       name
       weight_g
       description
       fitted_uvdb_vehicle_definitions {
         items {
           name
           uvdb_make {
             name
           }
           uvdb_model {
             name
           }
         }
       }
       gapc_part_type {
         id
         name
       }
       interchange {
         items {
           name
           mpn
           gapc_brand {
             id
             name
           }
         }
       }
     }
     
   }
 }
}
{% c-block-end %}

Integration Guides

Marketplace/platform integration

If you are the technical lead for a platform or marketplace integration, connecting buyers looking for specific parts, with sellers who have pre-listed their parts.

Quoting/estimation engine

If you manage a platform connecting potential buyers / companies with part suppliers.

Manufacturer data infrastructure

If you are a parts manufacturer wanting to standardize your part / vehicle fitment data to communicate in a standard way with trading partners, marketplaces, and even your own site.

Distributor data infrastructure

If you are a parts distributor wanting to communicate in a standard way with suppliers, marketplaces, and even your own site.

Example queries

UVDB

UVDB (Universal Vehicle Database) is used to query all information relating to vehicles.

For example, you can query vehicle makes.

{% c-block language="Javascript" %}
{
 uvdb {
   search_uvdb_makes(limit:500) {
     items {
       id
       name
     }
   }
 }
}
{% c-block-end %}

And models, based on the make.

{% c-block language="Javascript" %}
{
 uvdb {
   search_uvdb_models(uvdb_make_id: "UMAK1372", limit: 500) {
     items {
       id
       name
     }
   }
 }
}
{% c-block-end %}

You can then query vehicle definitions base on the make/model/year.

{% c-block language="Javascript" %}
{
 uvdb {
   search_uvdb_vehicle_definitions(
     vehicle_instance: {
       uvdb_make_id: "UMAK1372"
       uvdb_model_id: "UMOD67209"
       uvdb_year_id: 2015
     }
   ) {
     items {
       id
       description
       uvdb_make {
         name
       }
       uvdb_models {
         id
         name
       }
       uvdb_submodels {
         id
         name
       }
       uvdb_engine_base {
         id
         name
       }
       uvdb_fuel_type {
         id
         name
       }
       uvdb_drive_type {
         id
         name
       }
       uvdb_engine_version {
         id
         name
       }
     }
   }
 }
}
{% c-block-end %}


GAPC

Finally, you could see all the GAPC Parts that fit by filtering by the vehicle base properties.

{% c-block language="Javascript" %}
{
 gapc {
   search_gapc_parts(
     vehicle_instance: {
       uvdb_make_id: "UMAK1372"
       uvdb_model_id: "UMOD67209"
       uvdb_year_id: 2015
     }
   ) {
     items {
       id
       name
       gapc_brand {
         id
         name
       }
       gapc_part_type {
         id
         name
       }
     }
   }
 }
}
{% c-block-end %}

Example: Query store product details

{% c-block language="Javascript" %}
{
 me {
   store {
     id
     name
   }
 }
 search(store_id: "YOUR_STORE_ID_HERE", limit: 10, query: "") {
   products {
     items {
       id
       name
       price
       presentment_price {
         price
         display_price
         currency_code
       }
       images {
         thumb_url
         large_url
       }
       gapc_part {
         name
         barcode
         gapc_brand {
           name
         }
         fitted_uvdb_vehicle_definitions {
           items {
             id
             name
             uvdb_make {
               name
             }
             uvdb_models {
               name
             }
           }
         }
       }
     }
   }
 }
}
{% c-block-end %}

API V3 Final Update Changes

Overview

ID

  • Most of the id (Int type) has now become the [ID type](https://graphql.org/learn/schema/#scalar-types)
  • There are 2 kinds of ID , one has the 4 characters unique prefix before them, like UvdbMake UMAK1372 UvdbModel UMOD67209 , the other is uuid like GapcPart 0000000000000000000000000029a917
  • For the unique type of  ID , you can use the new endpoint resolve_unique_nodes to retrieve it, their types all implemented interface UniqueNode. More information please check GraphQL Interface.

{% c-block language="GraphQL" %}

{
 resolve_unique_nodes(ids: ["GBRN13461", "GBRN13461", "UMAK1372", "UMOD67209"]) {
   id
   name
   __typename
   ... on UvdbModel {
     i18n {
       pl {
         name
       }
     }
     uvdb_make {
       id
       name
     }
   }
 }
}
{% c-block-end %}

General

  • Majority of the search endpoints have been renamed to have a search_ prefix. Eg. uvdb_makes become search_uvdb_makes , search become search_products
  • Majority of the resolve endpoints have been renamed to have a resolve_ prefix. Eg. products become resolve_products , users become resolve_users

VehicleInstance

  • The input type VehicleInstanceFilter is used to filter in multiple endpoints (search search_uvdb_vehicle_definitions uvdb_dynamic_option_suggestions search_gapc_parts and many other), it's an object contains uvdb_make_id uvdb_model_id uvdb_year_id and 40 other base properties.
  • Most of the 40 base property id (except for uvdb_month_id because it's just 1~12) can be retrieved using resolve_unique_nodes endpoint.

UVDB

  • vehicle_resolve is removed because we no longer require uvdb_base_vehicle for searching and filtering
  • Children endpoints of vehicle_selector gets promoted into uvdb namespace. Majority of the children endpoints have been renamed to have a more consistent naming rule. Eg. uvdb_makes become search_uvdb_makes .  More examples below.
  • The endpoint uvdb_dynamic_option_suggestions is used to return dynamic options

{% c-block language="GraphQL" %}

{
 uvdb {
   uvdb_dynamic_option_suggestions(
     vehicle_instance: {
       uvdb_make_id: "UMAK1356"
       uvdb_year_id: 2010
       uvdb_model_id: "UMOD65333"
     }
     gapc_categorization: { gapc_category_id: "GCCA68" }
     limit: 3
   ) {
     suggestion_type
     uvdb_dynamic_options {
       id
       name
       __typename
     }
   }
 }
}
{% c-block-end %}

GAPC

  • Most of the endpoints have been renamed with same rule. The old parts now becomes search_gapc_parts and resolve_gapc_parts .  More examples below.
  • The fitment_check endpoint is add to the GapcPart . It takes VehicleInstanceFilter as a param and return precise result of if the part would fit the vehicle. In addition, it will promote to ask if more question should be ask to check.

{% c-block language="GraphQL" %}

{
 gapc {
   resolve_gapc_parts(id: "0000000000000000000002KA8E") {
     fitment_check(
       vehicle_instance: {
         uvdb_make_id: "UMAK1356"
         uvdb_year_id: 2010
         uvdb_model_id: "UMOD65333"
       }
     ) {
       is_fit
       is_universal
       has_fitment_information
       is_fitment_error
       note
       uvdb_dynamic_option_suggestions {
         suggestion_type
         uvdb_dynamic_options {
           id
           name
           __typename
         }
       }
     }
   }
 }
}
{% c-block-end %}

Examples

UVDB

Before

UVDB (Universal Vehicle Database) is used to query all information relating to vehicles.

For example, you can query vehicle makes.

{% c-block language="GraphQL" %}
{
 uvdb {
   vehicle_selector {
     uvdb_makes(limit:500) {
       items {
         id
         name
       }
     }
   }
 }
}
{% c-block-end %}

After

{% c-block language="GraphQL" %}

{
 uvdb{
   search_uvdb_makes(limit:500){
     items{
       id
       name
     }
   }
 }
}
{% c-block-end %}

Before

And models, based on the make.

{% c-block language="GraphQL" %}

{
 uvdb {
   vehicle_selector {
     uvdb_models(uvdb_make_id:1372, limit:500) {
       items {
         id
         name
       }
     }
   }
 }
}
{% c-block-end %}

After

{% c-block language="GraphQL" %}

{
 uvdb{
   search_uvdb_models(uvdb_make_id:"UMAK1372", limit:500){
     items{
       id
       name
     }
   }
 }
}
{% c-block-end %}

Before

You can then query vehicle definitions base on the model.

{% c-block language="GraphQL" %}

{
uvdb {
   vehicle_selector {
     uvdb_vehicle_definitions(uvdb_model_id:67209) {
       items {
         uvdb_make {
           name
         }
         uvdb_model {
           name
         }
       }
     }
   }
 }
{% c-block-end %}

After

the UvdbVehicleDefintions will return all the models linked to it now

{% c-block language="GraphQL" %}

{
 uvdb{
   search_uvdb_vehicle_definitions(vehicle_instance:{
     uvdb_make_id:"UMAK1372",
     uvdb_model_id:"UMOD67209",
     uvdb_year_id:2007
   }){
     items{
       id
       name
       uvdb_make{
         name
       }
       uvdb_models{
         name
       }
     }
   }
 }
}
{% c-block-end %}

GAPC

Before

Finally, you could see all the GAPC Parts that fit by filtering by the vehicle definition.

{% c-block language="GraphQL" %}

{
 gapc {
   parts(vehicle: {vehicle_definition_id:1000}, limit:5) {
     items {
       name
       barcode
       gapc_brand {
         name
       }
       gapc_part_type {
         name
       }
     }
   }
 }
}
{% c-block-end %}


After

Instead of using vehicle_definition_id , you will need to construct the vehicle instance object to query fitted parts.

{% c-block language="GraphQL" %}
{
 gapc{
   search_gapc_parts(vehicle_instance:{
     uvdb_make_id:"UMAK1372",
     uvdb_model_id:"UMOD67209",
     uvdb_year_id:2007
   },
     limit:5
   ){
     items{
       id
       name
       gapc_brand{
         id
         name
       }
       gapc_part_type{
         id
         name
       }
     }
   }
 }
}
{% c-block-end %}

Before

Example: Query store product details

{% c-block language="GraphQL" %}

{
 me {
   store {
     id
     name
   }
 }
 search(store_id: YOUR_STORE_ID_HERE, limit: 10, q: "") {
   products {
     items {
       id
       name
       price
       presentment_price {
         price
         display_price
         currency_code
       }
       images {
         thumb_url
         large_url
       }
       gapc_part {
         name
         barcode
         gapc_brand {
           name
         }
         fitted_uvdb_vehicle_definitions {
           items {
             id
             name
             uvdb_make {
               name
             }
             uvdb_model {
               name
             }
           }
         }
       }
     }
   }
 }
}
{% c-block-end %}

After

{% c-block language="GraphQL" %}

{
 me {
   store {
     id
     name
   }
 }
 search_products(store_id: YOUR_STORE_ID_HERE, limit: 10, query:"") {
   products {
     items {
       id
       name
       price
       presentment_price {
         price
         display_price
         currency_code
       }
       images {
         thumb_url
         large_url
       }
       gapc_part {
         name
         barcode
         gapc_brand {
           name
         }
         fitted_uvdb_vehicle_definitions {
           items {
             id
             name
             uvdb_make {
               name
             }
             uvdb_models {
               name
             }
           }
         }
       }
     }
   }
 }
}
{% c-block-end %}

Terminology

To be updated...

  • UVDBThe Universal Vehicle Database
  • GAPCThe Global Auto Parts Catalog
  • GAPC PartA part in the Global Auto Parts Catalog
  • ProductA PartsPal inventory inventory item