Normalize

How it works: You send JSON (free text or structured select data) and your X-API-Key; the service normalizes vehicle fields (brand, model, year, etc.) and returns structured data.

This page shows how to use the VehiCore Normalize APIs to standardize vehicle-related text and structured data. All endpoints expect JSON and the X-API-Key header. To get a key, register and purchase at vehicore.pro/api-keys.

Normalize Text

Takes free-form text and returns normalized vehicle fields.

POST /api/normalize/normalize-text

Request

Headers

Field	Type	Required	Description
`Content-Type`	string	Yes	Must be `application/json`.
`X-API-Key`	string	Yes	Your API key.

Body (JSON)

Field	Type	Required	Description
`text`	string	Yes	Raw text to normalize (e.g. "BMW 320d 2018 automatic").
`country`	string	Yes	Country/market code for normalization (e.g. `italy`).

Example request

curl -X POST "https://api.vehicore.pro/api/normalize/normalize-text" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"text": "BMW 320d 2018 automatic", "country": "italy"}'

const response = await fetch('https://api.vehicore.pro/api/normalize/normalize-text', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.VEHICORE_API_KEY,
  },
  body: JSON.stringify({ text: 'BMW 320d 2018 automatic', country: 'italy' }),
});
const data = await response.json();

import os
import requests

url = "https://api.vehicore.pro/api/normalize/normalize-text"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": os.environ["VEHICORE_API_KEY"],
}
payload = {"text": "BMW 320d 2018 automatic", "country": "italy"}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

RequestBody body = RequestBody.create(
    "{\"text\":\"BMW 320d 2018 automatic\",\"country\":\"italy\"}",
    MediaType.parse("application/json"));

Request request = new Request.Builder()
    .url("https://api.vehicore.pro/api/normalize/normalize-text")
    .header("X-API-Key", System.getenv("VEHICORE_API_KEY"))
    .post(body)
    .build();

try (Response response = new OkHttpClient().newCall(request).execute()) {
    System.out.println(response.body().string());
}

payload := []byte(`{"text":"BMW 320d 2018 automatic","country":"italy"}`)
req, _ := http.NewRequest("POST", "https://api.vehicore.pro/api/normalize/normalize-text", bytes.NewReader(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-Key", os.Getenv("VEHICORE_API_KEY"))
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
io.Copy(os.Stdout, resp.Body)

Response

On success the API returns normalized fields (brand, model, year, gearbox, combustion, country, etc.). See Swagger for the full response schema.

Possible errors

All error responses use the shape { "message": "Human-readable text", "code": "OPTIONAL_CODE" }. See Error responses for details.

Status	Code	Description
400	`VALIDATION_ERROR`	Bad Request — invalid JSON, missing `text` or `country`, or other validation failure.
401	`UNAUTHORIZED`	Unauthorized — missing or invalid `X-API-Key`.
402	`INSUFFICIENT_CREDITS`	Payment Required — insufficient credits. Purchase more from Billing.
500	—	Internal Server Error — unexpected server error; retry later.

Normalize Select Data

Takes structured fields and returns normalized/canonical values.

POST /api/normalize/normalize-select-data

Request

Headers

Field	Type	Required	Description
`Content-Type`	string	Yes	Must be `application/json`.
`X-API-Key`	string	Yes	Your API key.

Body (JSON) — country is required. Other fields are optional; send only the fields you want to normalize.

Field	Type	Required	Description
`country`	string	Yes	Country/market code (e.g. `italy`).
`brand`	string	No	e.g. `bmw`.
`model`	string	No	e.g. `320`.
`gearbox`	string	No	e.g. `automatic`, `manual`.
`combustion`	string	No	e.g. `diesel`, `petrol`, `electric`.
`bodyType`	string	No	e.g. `sedan`.
`color`	string	No	e.g. `black`.
`year`	number	No	e.g. `2020`.
`numberOfDoors`	number	No	e.g. `4`.
`numberOfSeats`	number	No	e.g. `5`.
`traction`	string	No	e.g. `fwd`.
`milage`	number	No	e.g. `50000`.

Example request

curl -X POST "https://api.vehicore.pro/api/normalize/normalize-select-data" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"brand":"bmw","model":"320","gearbox":"automatic","combustion":"diesel","bodyType":"sedan","country":"italy"}'

const response = await fetch('https://api.vehicore.pro/api/normalize/normalize-select-data', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.VEHICORE_API_KEY,
  },
  body: JSON.stringify({
    brand: 'bmw',
    model: '320',
    gearbox: 'automatic',
    combustion: 'diesel',
    bodyType: 'sedan',
    country: 'italy',
  }),
});
const data = await response.json();

import os
import requests

url = "https://api.vehicore.pro/api/normalize/normalize-select-data"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": os.environ["VEHICORE_API_KEY"],
}
payload = {
    "brand": "bmw",
    "model": "320",
    "gearbox": "automatic",
    "combustion": "diesel",
    "bodyType": "sedan",
    "country": "italy",
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

String json = "{\"brand\":\"bmw\",\"model\":\"320\",\"gearbox\":\"automatic\",\"combustion\":\"diesel\",\"bodyType\":\"sedan\",\"country\":\"italy\"}";
RequestBody body = RequestBody.create(json, MediaType.parse("application/json"));

Request request = new Request.Builder()
    .url("https://api.vehicore.pro/api/normalize/normalize-select-data")
    .header("X-API-Key", System.getenv("VEHICORE_API_KEY"))
    .post(body)
    .build();

try (Response response = new OkHttpClient().newCall(request).execute()) {
    System.out.println(response.body().string());
}

payload := []byte(`{"brand":"bmw","model":"320","gearbox":"automatic","combustion":"diesel","bodyType":"sedan","country":"italy"}`)
req, _ := http.NewRequest("POST", "https://api.vehicore.pro/api/normalize/normalize-select-data", bytes.NewReader(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-Key", os.Getenv("VEHICORE_API_KEY"))
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
io.Copy(os.Stdout, resp.Body)

Response

On success the API returns normalized values for each provided field. See Swagger for the full response schema.

Possible errors

Status	Code	Description
400	`VALIDATION_ERROR`	Bad Request — invalid JSON, missing `country`, or other validation failure.
401	`UNAUTHORIZED`	Unauthorized — missing or invalid `X-API-Key`.
402	`INSUFFICIENT_CREDITS`	Payment Required — insufficient credits. Purchase more from Billing.
500	—	Internal Server Error — unexpected server error; retry later.

Normalize

On this page