Toyota Europe Dealers API

Overview

This API provides accurate information about the Lexus and Toyota dealer network in Europe. We have various amounts of public information such as opening hours, offered services and contact information.

This API is used to power features on the Toyota websites, but everyone is free to use it for their own usecases.

Authorization

While we do not intend to heavily secure this data, the API does require an API-key, so that we can monitor the API usage and inform you of relevant changes. These API keys can be obtained after registration on the following website.

API keys need to be supplied with each request to the service as a bearer token in an Authorization header.

curl -XGET -H 'Authorization: Bearer <your_token>' 'https://a2d-api.toyota-europe.com'

The application to provision API-keys is still in development. Until this service becomes available, any token supplied in the Authorization header will be considered valid. We highly recommend that you use an email address on which we can contact you as a token. This will allow us to contact you when the API-key provisioning becomes available, instead of you finding out the hard way.

Schema and Versioning

The dealers are represented by a common schema with optional extensions by country. At the moment no country has any extensions.

The schema of the data is versioned. Older versions of the schema will be supported up to 6 months to help with the transition. Only breaking changes (such as changes in type of existing attributes) will cause the version to increase. This means that clients are supposed to ignore attributes they do not use. New attributes will only be added to the latest version of the schema.

You can specify a specific version of the schema in the accept header. The schema version is included in the response in the custom X-A2D-Media-Type header.

To provide backwards compatibility the API will currently return version 1 in case no accept headers are specified. This feature will be removed when support for version 1 is dropped. From that point on a valid accept header specifying the schema version will be mandatory!

If you are relying on fields which are not specified in the included json schema's, please drop us a line on a2dsupport@toyota-europe.com

Version 1

Version 2

Notable changes:

  • email and phoneNumber attributes now contain an array of strings rather than just a single string

Version 3

Notable changes:

  • All string fields are now analyzed. A non analyzed field was added to the index under <fieldname>.raw. Practically speaking this means that if you have a terms query you should either change that to a match query, or change the field name to <fieldname>.raw. The examples have been updated where appropriate.
  • The operation codes have changed to a format without spaces. A mapping table can be found here.
  • All urls are now part of a url attribute, with a similar structure to email and phoneNumber

API

The dealer API is powered by Elasticsearch and exposes its API more or less directly. All queries you can do with Elasticsearch you can do here, provided the necessary Authorization headers are present.

If you are using a client library for elasticsearch in your application, you can use a2d as index name and a 2 digit country code (eg. be) as type.

To get you started we have provided some example queries. For more advances use cases we refer you to the Elasticsearch documentation

Here are some general pointers:

  • If you want to search on multiple fields, you need to use a bool query
  • By default the API will return the first 10 documents, if you need more you should explicitly specify a higher upper bound or paginate using an offset. Another way to go around this is to use two queries:
    1. Run the query against the _count endpoint rather than the _search endpoint: this will return the number of hits
    2. Run the query against the _search endpoint explicitly asking for that number of hits
  • The output is contained in the hits.hits array
  • The dealer document is contained in the _source object
  • All string fields are analyzed, which means they do a fuzzy match. If you want to query them you need to use a match query operator.
  • Exact match queries can be done using a terms query on the <fieldname>.raw non analyzed field. (See the examples)

We will be upgrading to Elasticsearch 5 in the future. This version of Elasticsearch has removed the filtered query, which was featured in our examples. If you are using the filtered query, you can refactor them as described here: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-filtered-query.html

More information on breaking changes in Elasticsearch 5 can be found here: https://www.elastic.co/guide/en/elasticsearch/reference/5.0/breaking_50_search_changes.html

Examples

This section provides some example queries in curl format. They should be easy enough to adapt to your platform of choice.

Get dealer via UUID

Query

curl -XGET -H 'Authorization: Bearer my@email.com' -H 'Accept: application/vnd.toyota-europe.a2d.v3+json' 'https://a2d-api.toyota-europe.com/de/00CD0-E9EAD-1D654-90000-01350-3'

Output

{
  "_index": "v3_1459414547478",
  "_type": "de",
  "_id": "00CD0-E9EAD-1D654-90000-01350-3",
  "_version": 1,
  "found": true,
  "_source": {
    "addresses": [
      {
        "addressLine1": "Ollenhauer Str. 9-13",
        "addressLine2": null,
        "addressCode": null,
        "addressCountry": "DE",
        "authorisedRepairer": false,
        "authorisedRetailer": false,
        "city": "Berlin",
        "customRegion": null,
        "defaultAddress": true,
        "endDate": null,
        "geoLocation": {
          "lon": "13.32974117",
          "lat": "52.5671516"
        },
        "language": "de",
        "operations": [
          "ShowRoom",
          "WorkShop"
        ],
        "province": null,
        "region": "Berlin",
        "startDate": null,
        "status": "Active",
        "vatRegion": null,
        "zip": "13403"
      }
    ],
    "applications": {
      "NMSC": {
        "applicationCode": "NMSC",
        "applicationName": "NMSC local dealer database",
        "externalID": "68005"
      },
      "DF": {
        "applicationCode": "DF",
        "applicationName": "Dealer Finder",
        "externalID": "37C7B869-352E-11D5-A1C8-00508B8B464E"
      }
    },
    "brands": [
      "Lexus"
    ],
    "country": "DE",
    "dealerProfession": null,
    "defaultAddress": {
      "addressLine1": "Ollenhauer Str. 9-13",
      "addressLine2": null,
      "addressCode": null,
      "addressCountry": "DE",
      "authorisedRepairer": false,
      "authorisedRetailer": false,
      "city": "Berlin",
      "customRegion": null,
      "defaultAddress": true,
      "endDate": null,
      "geoLocation": {
        "lon": "13.32974117",
        "lat": "52.5671516"
      },
      "language": "de",
      "operations": [
        "ShowRoom",
        "WorkShop"
      ],
      "province": null,
      "region": "Berlin",
      "startDate": null,
      "status": "Active",
      "vatRegion": null,
      "zip": "13403"
    },
    "defaultEmail": "info.Berlin@lexus.de",
    "defaultPhoneNumber": "030/498808-7000",
    "email": {
      "ContactUs": [
        "info.Berlin@lexus.de"
      ]
    },
    "language": "de",
    "lastModificationDate": "12/08/2015 11:01:17.363",
    "name": "Lexus Forum Berlin&lt;br&gt;M.C.F. Motor Company Fahrzeugvertriebs GmbH",
    "latinName": null,
    "operatingCompany": {
      "addresses": [],
      "applications": {},
      "brands": [
        "Lexus"
      ],
      "defaultAddress": null,
      "name": "Lexus Forum Berlin&lt;br&gt;M.C.F. Motor Company Fahrzeugvertriebs GmbH",
      "primaryOutlet": "00CD0-E9EAD-1D654-90000-01350-3",
      "defaultEmail": null,
      "defaultPhoneNumber": null,
      "email": null,
      "phoneNumber": null,
      "status": "Open",
      "taxOffice": null,
      "uuid": "00CD0-E9EAD-1D626-68400-01350-3",
      "vat": null,
      "nmscCode": "TDG"
    },
    "operations": [
      "WorkShop",
      "ShowRoom"
    ],
    "openDays": [],
    "outletAfterSales": {},
    "outletMarketing": {
      "marketingName": "Lexus Forum Berlin&lt;br&gt;M.C.F. Motor Company Fahrzeugvertriebs GmbH",
      "areas": "WorkShop\t\t\t\t\t        \t\t\t\t      \t\t\t\t      \t\t\t\t"
    },
    "phoneNumber": {
      "ContactUs": [
        "030/498808-7000"
      ],
      "Fax1": [
        "030/498808-7090"
      ]
    },
    "primaryOutlet": true,
    "region": "Berlin",
    "status": "Open",
    "url": {
      "WebsiteURL": [
        "http://www.lexusforum-berlin.de/reinickendorf"
      ]
    },
    "uuid": "00CD0-E9EAD-1D654-90000-01350-3"
  }
}

Get dealer via local system ID

Query

curl -XGET -H 'Authorization: Bearer my@email.com' -H 'Accept: application/vnd.toyota-europe.a2d.v3+json' 'https://a2d-api.toyota-europe.com/de/_search?pretty' -d '{
  "query": {
    "term": {"applications.NMSC.externalID.raw": "68005"}
  }
}'
curl -XGET -H 'Authorization: Bearer my@email.com' -H 'Accept: application/vnd.toyota-europe.a2d.v3+json' 'https://a2d-api.toyota-europe.com/de/_search?q=applications.NMSC.externalID.raw:68005'

Output

{
  "took": 230,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "hits": {
    "total": 1,
    "max_score": 8.554073,
    "hits": [
      {
        "_index": "v3_1459414547478",
        "_type": "de",
        "_id": "00CD0-E9EAD-1D654-90000-01350-3",
        "_score": 8.554073,
        "_source": {
          "addresses": [
            {
              "addressLine1": "Ollenhauer Str. 9-13",
              "addressLine2": null,
              "addressCode": null,
              "addressCountry": "DE",
              "authorisedRepairer": false,
              "authorisedRetailer": false,
              "city": "Berlin",
              "customRegion": null,
              "defaultAddress": true,
              "endDate": null,
              "geoLocation": {
                "lon": "13.32974117",
                "lat": "52.5671516"
              },
              "language": "de",
              "operations": [
                "ShowRoom",
                "WorkShop"
              ],
              "province": null,
              "region": "Berlin",
              "startDate": null,
              "status": "Active",
              "vatRegion": null,
              "zip": "13403"
            }
          ],
          "applications": {
            "NMSC": {
              "applicationCode": "NMSC",
              "applicationName": "NMSC local dealer database",
              "externalID": "68005"
            },
            "DF": {
              "applicationCode": "DF",
              "applicationName": "Dealer Finder",
              "externalID": "37C7B869-352E-11D5-A1C8-00508B8B464E"
            }
          },
          "brands": [
            "Lexus"
          ],
          "country": "DE",
          "dealerProfession": null,
          "defaultAddress": {
            "addressLine1": "Ollenhauer Str. 9-13",
            "addressLine2": null,
            "addressCode": null,
            "addressCountry": "DE",
            "authorisedRepairer": false,
            "authorisedRetailer": false,
            "city": "Berlin",
            "customRegion": null,
            "defaultAddress": true,
            "endDate": null,
            "geoLocation": {
              "lon": "13.32974117",
              "lat": "52.5671516"
            },
            "language": "de",
            "operations": [
              "ShowRoom",
              "WorkShop"
            ],
            "province": null,
            "region": "Berlin",
            "startDate": null,
            "status": "Active",
            "vatRegion": null,
            "zip": "13403"
          },
          "defaultEmail": "info.Berlin@lexus.de",
          "defaultPhoneNumber": "030/498808-7000",
          "email": {
            "ContactUs": [
              "info.Berlin@lexus.de"
            ]
          },
          "language": "de",
          "lastModificationDate": "12/08/2015 11:01:17.363",
          "name": "Lexus Forum Berlin&lt;br&gt;M.C.F. Motor Company Fahrzeugvertriebs GmbH",
          "latinName": null,
          "operatingCompany": {
            "addresses": [],
            "applications": {},
            "brands": [
              "Lexus"
            ],
            "defaultAddress": null,
            "name": "Lexus Forum Berlin&lt;br&gt;M.C.F. Motor Company Fahrzeugvertriebs GmbH",
            "primaryOutlet": "00CD0-E9EAD-1D654-90000-01350-3",
            "defaultEmail": null,
            "defaultPhoneNumber": null,
            "email": null,
            "phoneNumber": null,
            "status": "Open",
            "taxOffice": null,
            "uuid": "00CD0-E9EAD-1D626-68400-01350-3",
            "vat": null,
            "nmscCode": "TDG"
          },
          "operations": [
            "WorkShop",
            "ShowRoom"
          ],
          "openDays": [],
          "outletAfterSales": {},
          "outletMarketing": {
            "marketingName": "Lexus Forum Berlin&lt;br&gt;M.C.F. Motor Company Fahrzeugvertriebs GmbH",
            "areas": "WorkShop\t\t\t\t\t        \t\t\t\t      \t\t\t\t      \t\t\t\t"
          },
          "phoneNumber": {
            "ContactUs": [
              "030/498808-7000"
            ],
            "Fax1": [
              "030/498808-7090"
            ]
          },
          "primaryOutlet": true,
          "region": "Berlin",
          "status": "Open",
          "url": {
            "WebsiteURL": [
              "http://www.lexusforum-berlin.de/reinickendorf"
            ]
          },
          "uuid": "00CD0-E9EAD-1D654-90000-01350-3"
        }
      }
    ]
  }
}

Get the number of Lexus dealers in Germany

Query

curl -XPOST -H 'Authorization: Bearer my@email.com' 'https://a2d-api.toyota-europe.com/de/_count?pretty' -H 'Accept: application/vnd.toyota-europe.a2d.v3+json' -d '{
  "query": {
    "term": {"brands.raw": "Toyota"}
  }
}'
curl -XPOST -H 'Authorization: Bearer my@email.com' -H 'Accept: application/vnd.toyota-europe.a2d.v3+json' 'https://a2d-api.toyota-europe.com/outlet/_count?q=brands.raw:Toyota&pretty'

Output

{
  "count" : 676,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "failed" : 0
  }
}

Get all Toyota dealers for Germany

Query

curl -XPOST -H 'Authorization: Bearer my@email.com' 'https://a2d-api.toyota-europe.com/de/_search?pretty' -H 'Accept: application/vnd.toyota-europe.a2d.v3+json' -d '{
  "query": {
    "term": {"brands.raw": "Toyota"}
  },
  "size": 676
}'
curl -XPOST -H 'Authorization: Bearer my@email.com' -H 'Accept: application/vnd.toyota-europe.a2d.v3+json' 'https://a2d-api.toyota-europe.com/de/_search?q=brands.raw:Toyota&size=676&pretty'

Output

{
  "took" : 3,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "failed" : 0
  },
  "hits" : {
    "total" : 101,
    "max_score" : 3.9336994,
    "hits" : [
      {
        "_index" : "a2d",
        "_type" : "outlet",
        "_id" : "00CD0-E9EAD-1D213-CB200-01350-3",
        "_score" : 3.9336994,
        "_source": {"dealer_record_1"}
      },
      {
        "_index" : "a2d",
        "_type" : "outlet",
        "_id" : "00CD0-E9EAD-1D654-90000-01350-3",
        "_score" : 3.9336994,
        "_source": {"dealer_record_2"}
      },
      ...
    ]
  }
}

Get all Lexus dealers in a 5 km radius around a location

Query

curl -XPOST -H 'Authorization: Bearer my@email.com' 'https://a2d-api.toyota-europe.com/de/_search?pretty' -H 'Accept: application/vnd.toyota-europe.a2d.v3+json' -d '{
  "query": {
    "bool": {
      "must": {
        "term": {"brands.raw": "Lexus"}
      },
      "filter": {
        "geo_distance": {
          "distance": "5km",
          "addresses.geoLocation" : {
            "lat": 51.22,
            "lon": 6.81
          }
        }
      }
    }
  }
}'

Output

{
  "took" : 442,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "failed" : 0
  },
  "hits" : {
    "total" : 1,
    "max_score" : 2.956398,
    "hits" : [
      {
        "_index" : "a2d",
        "_type" : "outlet",
        "_id" : "00CD0-E9EAD-1D2E6-7C600-01350-3",
        "_score" : 2.956398,
        "_source": {"dealer_record_1"}
      }
    ]
  }
}
\