Documentation

Auto-Data.net One-Call API Documentation

The service is a One-call based XML/JSON API. When you place an order or request a demo, in both cases you will automatically get a demo link for a call with a limited number of records of all fields you have chosen. You have to store the data in your own database.

The field names in all downloadable formats are the same. Here you can download the full XML schema, and here the full JSON schema. Numbers in the schema files are field numbers in the fields description file. Here is a file with fields description (xlsx) (or ods).

Quick start

  1. Step 1Get your access codePlace an order or request a demo on the Get a Quote page. You get a demo link by email.
  2. Step 2Download the full fileImport it into your own database and save the date of the download.
  3. Step 3Download updatesRegularly get only the changes after the saved date. See How to get updates.

Parameters overview

All parameters are GET parameters of the same link and can be combined.

ParameterValueIf omittedDescription
codeyour access codeRequiredIdentifies your access.
formatjsonXMLResponse format. See XML/JSON download.
updateyyyy-mm-ddFull dataOnly changes after this date. See How to get updates.
brandscomma separated brand namesAll brandsData only for these brands. See Separate brand(s) download.
langlanguage codeYour default languageLanguage of the text values. See Language support.
mapping1Data is downloadedDownload the list of IDs and text values instead of the data. See ID fields and mapping.

XML / JSON download

The default format is XML. JSON format is also available. To download JSON format you have to add format=json to the call link.

https://api.auto-data.net/?code={your code here}&format=json

The XML root element uses the namespace http://www.auto-data.net/. If you parse the XML with XPath, you have to register this namespace.

Data rules

  • All values are strings, including numbers. The Value type column in the fields description (xlsx or ods) shows what the string contains: int, float, string, year or datetime. Decimal numbers use a dot, for example "5.3".
  • Empty fields are not present in the file. If a field is missing, there is no data for it.
  • Fields that can contain a range (for example "height": "1450-1470") have normalized fields with the minimum and maximum value (heightMin, heightMax).
  • Cars with an alternative fuel have additional fields with a suffix for the fuel: LPG, CNG, E85 or E100 (for example powerHpLPG, fuelConsumptionCombinedCNG).
  • Fields starting with standard (for example standardFCc, standardCO2) show the standard the related values are measured by (WLTP, NEDC, etc.).
  • Text fields that come from a predefined list have an additional ID field. See ID fields and mapping.

File generation and cache

Each call generates a file. If you make the same call again within 5 hours, you will get the lastly generated file. Every combination of parameters (lang, brands, update, format, mapping) is a separate file with its own 5 hours period. For example, calls with lang=de and lang=fr generate two different files.

Generating a full file may take some time. While a file is being generated, the same call returns an error (see Errors). Wait until the first call finishes, do not repeat it.

In demo mode the file is generated only once.

How to get updates

There are several ways to update your own database with fresh data. The easiest way is to download an update file with the changes in the data after the date you choose. Just add GET parameter update with value the date in format yyyy-mm-dd and you will receive only changes from this date till the moment. If the date is not valid, you will receive the full file.

When you update your database, do not forget to update parent parameters in the structure, as well. With the updates you will also receive a deleted field/tag, that describes deleted models/generations/images/modifications for the chosen period. Please, check the XML schema or the JSON schema and fields description (xlsx) (or ods) for more information.

Recommended way to keep your database up to date:

  1. Download the full file once and import it.
  2. Save the date of the download.
  3. Regularly download an update file with update set to the saved date.
  4. Add or replace the received records and delete the records listed in deleted.
  5. Save the new date and repeat.

Important! Updates are valid for each date after 2021-02-19. You cannot download updates in demo mode!

Examples:

https://api.auto-data.net/?code={your code here}&update=2021-02-20
https://api.auto-data.net/?code={your code here}&format=json&update=2021-02-20

Separate brand(s) download

With the main link for your access you will get data for all available brands (or those you have access to). If you would like to download the data for a specific brand or brands, you can do that by adding a GET parameter brands to your link, and list (comma separated) the brand or brands you would like to download the data for. Brand names have to be the same as in the lists below. Use + for spaces in brand names. Unknown brand names are ignored.

Examples:

https://api.auto-data.net/?code={your code here}&brands=Audi
https://api.auto-data.net/?code={your code here}&brands=Audi,BMW&format=json
https://api.auto-data.net/?code={your code here}&brands=Audi,BMW&format=json&update=2021-02-20
https://api.auto-data.net/?code={your code here}&brands=Alfa+Romeo,Audi

All available in the database brands can be downloaded: comma separated or new line separated.

Language support

We offer our data in 18 languages. When you place an order, you have to specify the default language for your access. You can download the data in each language with GET parameter lang and language code. If the language code is not valid, you will receive the data in your default language. Here are available language codes:

  • English en
  • Български bg
  • Русский ru
  • Deutsch de
  • Italiano it
  • Français fr
  • Español es
  • Ελληνικά gr
  • Türkçe tr
  • Română ro
  • Suomi fi
  • Svenska se
  • Norsk no
  • Polski pl
  • Português pt
  • Nederlands nl
  • Čeština cz
  • Magyar hu

Examples:

https://api.auto-data.net/?code={your code here}&lang=fi
https://api.auto-data.net/?code={your code here}&lang=de
https://api.auto-data.net/?code={your code here}&lang=de&format=json
https://api.auto-data.net/?code={your code here}&lang=de&format=json&update=2021-02-20
https://api.auto-data.net/?code={your code here}&brands=Alfa+Romeo,Audi&lang=ru

ID fields and mapping

All text fields that come from a predefined list (fuel type, drive, body type, brakes, suspension, etc.) have an additional ID field next to them, for example fuel and fuelId. The ID values never change, so you can use them with your own translations instead of the text values. Fields with more than one value (like coupeId) contain a comma separated list of IDs, without spaces.

To get the list of all IDs and their text values, add GET parameter mapping to your link. The mapping contains only the fields you have access to. It supports lang and format parameters. Parameters brands and update are ignored.

Each dictionary in the mapping has a name (the name of the text field), the ID fields that use it and the list of items:

<mapping xmlns="http://www.auto-data.net/">
    <dictionary>
        <name>drive</name>
        <fields>driveId</fields>
        <item>
            <id>1</id>
            <value>Rear wheel drive</value>
        </item>
        ...
    </dictionary>
    ...
</mapping>

Examples:

https://api.auto-data.net/?code={your code here}&mapping=1
https://api.auto-data.net/?code={your code here}&mapping=1&format=json
https://api.auto-data.net/?code={your code here}&mapping=1&lang=de

Errors

If the call cannot be completed, you will receive HTTP status 403 with one of the following messages:

MessageReason
The token does not existWrong access code.
Your API key is disabled! Contact us!Your access is disabled.
Your API key has expired! Contact us!Your access has expired.
Your account is limited! Try a new request in N seconds!Your access has a limit for the time between calls.
The file is being created by another process! Please wait!The same file is being generated by a previous call. Wait until it finishes.

Brand logos

You also can access 2 sizes of brand logos: 40 x 40 px and 100 x 100 px. Logos are directly available via brand names. If a brand name contains a space, you have to replace spaces with underscores _. Logos are available as follows:

https://www.auto-data.net/img/logos/{brand_name}.png
https://www.auto-data.net/img/logos2/{brand_name}.png

Here are some examples:

https://www.auto-data.net/img/logos/Alfa_Romeo.png
https://www.auto-data.net/img/logos2/Alfa_Romeo.png
https://www.auto-data.net/img/logos/BMW.png
https://www.auto-data.net/img/logos/Mercedes-Benz.png

Downloadable files

Demo with real data

You may request a free demo on the Get a Quote page.

Get a Quote / Demo