Feed Specification for Partners

A1. Master Data API - overview and discovery

The entry point is the discovery index - a single URL that returns the list of all available feeds, their version and the time they were last generated:

GET https://nearcharger.sk/wp-json/nearcharger/v1/master-data

Endpoint	Contents
/master-data	Discovery index - list of feeds, schema_version, URLs, generated_at
/master-data/catalog	Vehicle catalog (variant + production year = 1 item), paginated, filters ?brand= and ?year=
/master-data/brands	Brand → model tree with stable IDs and slugs
/master-data/equipment	Equipment - categories + items
/master-data/enums	Other lookup tables: drivetrain, body type, segment, charge port, listing status, market, listing type, vehicle state, colors, seats, doors

Formats and pagination

• Format: ?format=json (default) or ?format=xml. We also accept the Accept: application/xml header.
• Pagination (only /catalog and the partner feed): ?page= and ?per_page=, maximum 500 items per page.
• All responses share a common envelope:

{
  "schema_version": 1,
  "generated_at": "2026-07-07T03:30:00+02:00",
  "page": 1,
  "total_pages": 3,
  "total_items": 1101,
  "items": [ ... ]
}

A2. Vehicle catalog (/catalog)

Each catalog item is a specific variant in a specific production year. A variant produced across several years therefore has multiple items - each with its own id. The mapping key is id (stable, never changes).

{
  "id": 15498,
  "slug": "mini-aceman-e-2190",
  "make": "Mini",
  "model": "Aceman",
  "version": "E",
  "year": 2024,
  "parent_model_slug": "mini-aceman",
  "brand_id": 125,
  "model_id": 704,
  "body_type": "suv",
  "segment": "jb-small",
  "drivetrain": "front",
  "charge_port": "ccs",
  "price_eur": 34990,
  "range_wltp": 310,
  "battery_kwh": 42.5,
  "power_kw": 135,
  "power_hp": 184,
  "battery_warranty_years": 8,
  "battery_warranty_km": 160000,
  "detail_url": "https://nearcharger.sk/..."
}

Filters

• ?brand=mini - slug or numeric ID of a brand or model (from /brands)
• ?year=2024 - a specific production year

A3. Lookup tables (/brands, /equipment, /enums)

Each lookup item has a stable id, an English slug and names in three languages:

{
  "id": 87,
  "slug": "heat-pump",
  "names": { "en": "Heat Pump", "sk": "Tepelné čerpadlo", "cz": "Tepelné čerpadlo" }
}

• /brands - brand → model tree. Brands and models are proper names (identical in every language), so instead of the names object they carry a single name field: { "id": 125, "slug": "mini", "name": "Mini", ... }. The aliases field is reserved for alternative spellings (e.g. VW vs. Volkswagen); it is empty in the current version.
• /equipment - equipment grouped into categories (each category has items).
• /enums - drivetrain (drivetrain), body type (body_type), segment, charge port (charge_port), listing status (listing_status), market (market), EV type (ev_type), listing type (ad_listing_type: new / used / demo vehicle), vehicle state (listing_state: e.g. first-owner, service-book, imported-vehicle, crashed) + canonical color, seats and doors values.

A4. Stability, versioning and caching

HTTP caching and the recommended pull

• Snapshots are generated once a day, at night (around 03:30). The recommended mode is a nightly / early-morning full pull; the data does not change during the day.
• Responses carry both ETag and Last-Modified. Send If-None-Match - if the content has not changed, you get a 304 Not Modified with no body and save bandwidth.
• Endpoints are rate-limited per IP. A nightly pull will never hit the limits; if you need a significantly higher frequency, get in touch.

A5. Your listings feed (token)

For every partner we can generate a private feed of their published listings on Nearcharger - for example to check what is currently online, or to sync back into your own system. The feed is protected by a static token handed over during onboarding:

GET https://nearcharger.sk/wp-json/nearcharger/v1/partner/{id}/listings?key={token}

Without a valid token the API returns 401. The feed contains only the public listing data (no contact details) and uses the same vehicle structure as your inbound feed:

{
  "id": 15498,
  "url": "https://nearcharger.sk/inzerat/...",
  "title": "Mini Aceman E, 2024",
  "status": "active",
  "car_version_id": 9876,
  "car_version_slug": "mini-aceman-e-2190",
  "make": "Mini",
  "model": "Aceman",
  "version": "E",
  "year": 2024,
  "price": { "amount": 34990, "currency": "EUR", "vat_deductible": true },
  "mileage_km": 12000,
  "color": "black",
  "vin": "...",
  "condition": "used",
  "state": ["first-owner", "service-book"],
  "equipment": ["heat-pump", "matrix-led"],
  "images": { "main": "https://...", "gallery": ["https://...", "https://..."] },
  "location": { "lat": 48.1, "lng": 17.1, "city": "Bratislava" }
}

1. Key information before you start

2. Technical requirements

Parameter	Requirement
Format	XML (preferred) or JSON
Encoding	UTF-8
Availability	Public HTTPS URL, or protected with Basic Auth / Bearer Token
Update frequency	At least once a day, ideally 2-4 times a day
Structure	Flat - each vehicle as a separate element / object in an array
Vehicle type	BEV only - fully electric vehicles
Feed size	Recommended limit of 500 vehicles per feed. For larger volumes, contact us in advance.

3. Required fields

#	Field	Type	Description	Example
1	id	string	Stable unique identifier of the vehicle in the partner system. Must not change during the lifetime of the listing.	"0300172062"
2	brand	string	Vehicle brand	"Škoda"
3	model	string	Vehicle model, ideally without the variant (the variant is a separate field below).	"Model Y"
4	variant	string	Specific version / trim level. Example split: brand Tesla · model Model Y · variant Long Range AWD. If your system does not distinguish model and variant, send them together in the model field and omit this one.	"Long Range AWD"
5	year_of_production	integer (YYYY)	Production year of the vehicle. For new cars this equals the registration year; for used cars it may differ.	2023
6	price	integer	Vehicle price including VAT (digits only, no spaces)	536000
7	currency	string (ISO 4217)	Price currency	"EUR" or "CZK"
8	vat_deductible	boolean (0/1)	Whether VAT is deductible	1
9	mileage_km	integer	Odometer reading in km. 0 for new vehicles.	55279
10	status	string	Current status. Accepted values: active, available, reserved, sold.	"active"
11	photos[]	array of URLs	At least 1 photo. Public HTTPS URLs. We recommend 10+ photos for better conversion.	["https://.../1.jpg", "https://.../2.jpg"]

Validation rules for required fields

• id must not contain spaces or special characters (allowed: A-Z, a-z, 0-9, dash, underscore)
• price must be > 0
• year_of_production must be between 2010 and the current year + 1
• mileage_km must be ≥ 0
• photos[] must contain at least 1 reachable HTTPS URL (not HTTP, no hotlink blocking)

4. Recommended fields (covered by the catalog, but ideally provided)

Field	Type	Why we want it	If you don't provide it
vin	string (17)	The most precise identifier + uniqueness across feeds (dedup)	We fall back to model + variant matching
engine / powertrain	string	Factory powertrain / motorization designation (not just battery capacity). Narrows down the exact catalog version, e.g. "Long Range Dual Motor" or "iV 60".	We try to derive it from model and variant
battery_kwh	integer/float	Battery capacity in kWh	From the EV Database catalog
wltp_range_km	integer	Range per the WLTP cycle	From the EV Database catalog
power_kw	integer	Power in kW	From the EV Database catalog
body_type	string	Body type (SUV, Hatchback, Sedan, Coupe, Liftback, Combi, MPV, Pickup)	From the EV Database catalog
drive	string	Drivetrain type (FWD, RWD, AWD, 4WD)	From the EV Database catalog
seats	integer	Number of seats	From the EV Database catalog, but it may not always match (the same version can come with 5 or 7 seats), so it is worth providing as well

5. Optional fields (specific to the individual listing)

We do not have these values in the catalog - they are specific to the individual vehicle. If you have them, send them - they increase the credibility of the listing (especially for used vehicles).

5.1 Vehicle registration and battery warranty

Field	Type	Description	Example
registration_year	integer (YYYY)	Year of the vehicle's first registration	2021
registration_month	integer (1-12)	Month of first registration (needed for a precise warranty calculation)	5 (= May)
battery_warranty	boolean (0/1)	Whether the vehicle has a valid battery warranty	1
battery_warranty_km	integer	Maximum km covered by the battery warranty (if it differs from the manufacturer default)	160000

5.2 Battery State of Health (SoH)

Field	Type	Description	Example
soh	integer (0-100)	Battery State of Health in % (current capacity vs. new)	94
soh_certificate_url	URL	Link to a PDF / image of the SoH measurement certificate (Aviloo, Moba, manufacturer, etc.)	"https://.../soh-cert.pdf"
soh_measurement_date	date (YYYY-MM-DD)	Date the SoH was measured (optional but useful)	"2024-11-15"

5.3 Vehicle appearance

Field	Type	Description	Example
color_exterior	string	Body color (as text). Ideally a canonical slug from /master-data/enums (e.g. black, pearl-white) - we map free text during onboarding.	"black metallic"
color_interior	string	Interior color / material	"black leather"
metallic	boolean (0/1)	Metallic paint	1

5.4 Location and seller

Field	Type	Description	Example
branch / location	string	City / branch where the vehicle is located	"Bratislava"
address	string	Full address (optional)	"Pestovateľská 5, Bratislava"
gps_lat	float	GPS coordinates - latitude	48.1486
gps_lng	float	GPS coordinates - longitude	17.1077

5.5 Price details

Field	Type	Description	Example
price_without_vat	integer	Price excluding VAT	442975
original_price	integer	Original price before discount (if the vehicle is discounted)	580000

5.6 Additional information

Field	Type	Description	Example
doors	integer	Number of doors. We do not have this in the catalog, so it is displayed only if you provide it.	5
description	string (text)	Free-text vehicle description (may contain HTML break tags)	"Vehicle in certified condition..."
equipment[]	array of strings	List of equipment. One item = one entry. Ideally send our slugs from /master-data/equipment (e.g. heat-pump) - we map your own names during onboarding.	["navigation", "cruise control", "leather seats"]
condition	string	We need to know whether the car is new, used or a demo vehicle: new, used, demo	"used"
state[]	array of strings	Vehicle state flags (multiple allowed). Ideally send our slugs from /master-data/enums (listing_state group): e.g. first-owner, service-book, imported-vehicle, crashed - we map free text during onboarding.	["first-owner", "service-book"]

6. Structure examples

6.1 XML - minimal example (required fields only)

<?xml version="1.0" encoding="UTF-8"?>
<feed>
  <vehicle>
    <id>VIN123456789</id>
    <brand>Škoda</brand>
    <model>Enyaq</model>
    <variant>iV 60</variant>
    <year_of_production>2023</year_of_production>
    <price>536000</price>
    <currency>CZK</currency>
    <vat_deductible>1</vat_deductible>
    <mileage_km>55279</mileage_km>
    <status>active</status>
    <photos>
      <photo>https://partner.sk/img/123/1.jpg</photo>
      <photo>https://partner.sk/img/123/2.jpg</photo>
    </photos>
  </vehicle>
</feed>

6.2 XML - full example (all fields)

<?xml version="1.0" encoding="UTF-8"?>
<feed>
  <vehicle>
    <!-- REQUIRED -->
    <id>VIN123456789</id>
    <brand>Škoda</brand>
    <model>Enyaq</model>
    <variant>iV 60</variant>
    <year_of_production>2023</year_of_production>
    <price>536000</price>
    <currency>CZK</currency>
    <vat_deductible>1</vat_deductible>
    <mileage_km>55279</mileage_km>
    <status>active</status>
    <photos>
      <photo>https://partner.sk/img/123/1.jpg</photo>
      <photo>https://partner.sk/img/123/2.jpg</photo>
    </photos>

    <!-- RECOMMENDED (from the catalog) -->
    <vin>TMBJB7NY2NF022916</vin>
    <engine>iV 60 (RWD)</engine>
    <battery_kwh>62</battery_kwh>
    <wltp_range_km>412</wltp_range_km>
    <power_kw>132</power_kw>
    <body_type>SUV</body_type>
    <drive>RWD</drive>
    <seats>5</seats>

    <!-- REGISTRATION + BATTERY WARRANTY -->
    <registration_year>2021</registration_year>
    <registration_month>5</registration_month>
    <battery_warranty>1</battery_warranty>
    <battery_warranty_km>160000</battery_warranty_km>

    <!-- SOH -->
    <soh>94</soh>
    <soh_certificate_url>https://partner.sk/cert/123-soh.pdf</soh_certificate_url>
    <soh_measurement_date>2024-11-15</soh_measurement_date>

    <!-- APPEARANCE -->
    <color_exterior>white</color_exterior>
    <color_interior>black leather</color_interior>
    <metallic>1</metallic>

    <!-- LOCATION -->
    <branch>Bratislava</branch>
    <gps_lat>48.1486</gps_lat>
    <gps_lng>17.1077</gps_lng>

    <!-- PRICING -->
    <price_without_vat>442975</price_without_vat>

    <!-- ADDITIONAL -->
    <doors>5</doors>
    <description><![CDATA[Vehicle in perfect condition, first owner.]]></description>
    <condition>used</condition>
    <state>
      <item>first-owner</item>
      <item>service-book</item>
    </state>
    <equipment>
      <item>heat pump</item>
      <item>navigation</item>
      <item>adaptive cruise control</item>
      <item>panoramic roof</item>
    </equipment>
  </vehicle>
</feed>

6.3 JSON - equivalent example

{
  "feed_version": "1.0",
  "generated_at": "2024-12-15T08:00:00Z",
  "vehicles": [
    {
      "id": "VIN123456789",
      "brand": "Škoda",
      "model": "Enyaq",
      "variant": "iV 60",
      "year_of_production": 2023,
      "price": 536000,
      "currency": "CZK",
      "vat_deductible": true,
      "mileage_km": 55279,
      "status": "active",
      "photos": [
        "https://partner.sk/img/123/1.jpg",
        "https://partner.sk/img/123/2.jpg"
      ],

      "vin": "TMBJB7NY2NF022916",
      "engine": "iV 60 (RWD)",
      "battery_kwh": 62,
      "wltp_range_km": 412,
      "power_kw": 132,
      "body_type": "SUV",
      "drive": "RWD",
      "seats": 5,

      "registration_year": 2021,
      "registration_month": 5,
      "battery_warranty": true,
      "battery_warranty_km": 160000,

      "soh": 94,
      "soh_certificate_url": "https://partner.sk/cert/123-soh.pdf",
      "soh_measurement_date": "2024-11-15",

      "color_exterior": "white",
      "color_interior": "black leather",
      "metallic": true,

      "branch": "Bratislava",
      "gps_lat": 48.1486,
      "gps_lng": 17.1077,

      "price_without_vat": 442975,

      "doors": 5,
      "description": "Vehicle in perfect condition, first owner.",
      "condition": "used",
      "state": ["first-owner", "service-book"],
      "equipment": [
        "heat pump",
        "navigation",
        "adaptive cruise control",
        "panoramic roof"
      ]
    }
  ]
}

7. Quick checklist before submitting your feed

• The feed contains BEV (fully electric) vehicles only
• The feed is available at a public HTTPS URL
• Encoding is UTF-8
• Every vehicle has a stable unique id
• Every vehicle has model and variant filled in (separately, or combined in the model field)
• Every vehicle has at least 1 photo at a public URL
• Every vehicle has a price and currency
• The status field contains one of: active / sold / reserved / available
• The year_of_production field is filled in (production year)
• Photos do not have hotlink protection enabled
• The feed is regenerated at least once a day

8. Frequently asked questions

9. Downloads

For self-service feed validation before submission, we provide machine-readable definitions of the listing template (part B):

File	Description
listing-template.schema.json	JSON Schema (draft 2020-12) for the JSON feed - validate your feed with e.g. ajv or an online validator
listing-template.xsd	XSD schema for the XML feed - validate with xmllint --schema or any XML tool