Normalize

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.

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 italy").

Example request

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

const response = await fetch('https://vehicore-api.dev-stage.fyi/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 italy' }),
});
const data = await response.json();

import os
import requests

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

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

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

Request request = new Request.Builder()
    .url("https://vehicore-api.dev-stage.fyi/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 italy"}`)
req, _ := http.NewRequest("POST", "https://vehicore-api.dev-stage.fyi/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 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) — All fields optional. Send only the fields you want to normalize.

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

Example request

curl -X POST "https://vehicore-api.dev-stage.fyi/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://vehicore-api.dev-stage.fyi/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://vehicore-api.dev-stage.fyi/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://vehicore-api.dev-stage.fyi/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://vehicore-api.dev-stage.fyi/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 or 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