Feed specification for partners

Nearcharger is an electric vehicle marketplace in Slovakia and Czechia. This document explains how to send us your vehicle inventory as a feed and what data we provide to help you. You do not need to read all of it: pick what you are working on.

How onboarding works

1. Map to our catalogOptional but the most reliable: store our vehicle IDs and value list slugs (A1 to A3).
2. Build the feedFollowing part 1. Validate it with the schema and compare it with the examples (section 9).
3. Send us the URLWe set up the download, map your own structure if needed, and hand over your token.
4. Check the resultThe reconciliation feed shows for every vehicle whether it is published and, if not, why (A6).

Part 1 Your feed for Nearcharger What you send us: structure, fields, examples and checks

1. Before you start

Your own field names are fine. If you use the names from this document, the mapping already exists and we connect your feed the day we receive its URL. If you have your own structure, we map your field names and values during onboarding. What matters is that the data is in the feed.

Technical data comes from our catalog. Once a vehicle is matched to an entry in our catalog (based on ev-database.org), we fill in the technical data it is missing. A vehicle that is not in the catalog shows only the data from your feed.

2. Technical requirements

3. Feed fields

Only three things are a hard requirement for the import: an identifier, the vehicle identity and a price. Other fields never block a listing, but without them it lacks something. Click a section to see the details.

3.1 Required: without these fields no listing is created

3.2 Needed: without these the listing lacks something

We would rather publish an incomplete listing than none, so a missing field is never reported as an error. Each field says what the listing loses.

3.3 Checks: what happens on an error

We would rather drop a bad value than lose the whole vehicle. A record is rejected only in the first six cases; the reconciliation feed then shows it as error with a code (A6.2).

4. Technical data

Our catalog has most of this data. It still helps us match the vehicle to the catalog, and for a vehicle outside the catalog it is the only source. Data about the specific vehicle (capacity, range, power, seats) takes precedence over the catalog; for body type and drivetrain the catalog wins and your value is a fallback.

5. Vehicle details

The catalog does not have this data because it belongs to the individual vehicle. For a used car it makes a big difference to buyer trust.

5.1 Registration and battery warranty

We calculate the remaining battery warranty ourselves: from the first registration we count down the warranty years of the matched catalog version. So we do not need the warranty end date, only the registration year and month.

5.2 Battery state of health (SoH)

For a used electric car, SoH is one of the most important figures. If you have a certificate for the measurement, send its link and we attach it to the listing.

5.3 Appearance and leasing

5.4 Location and branch contact

More than one branch? Send each vehicle's city, coordinates and contact. Otherwise every vehicle gets the address and number from your partner profile and buyers call the wrong branch.

5.5 Listing content

6. Examples

A full JSON record with every field. The same vehicle in XML is below; downloadable example feeds are in section 9.

{
  "feed_version": "1.0",
  "generated_at": "2026-09-23T04:00:00Z",
  "vehicles": [
    {
      "id": "SK-2021-0457",
      "brand": "Škoda",
      "model": "Enyaq",
      "price": 21900,

      "photos": [
        "https://partner.sk/img/0457/1.jpg",
        "https://partner.sk/img/0457/2.jpg"
      ],
      "status": "active",
      "variant": "iV 60",
      "mileage_km": 55279,
      "year_of_production": 2021,
      "vat_deductible": true,
      "currency": "EUR",

      "catalog_id": 14914,
      "vin": "TMBJB7NY2NF022916",
      "engine": "iV 60 (RWD)",
      "battery_kwh": 62,
      "wltp_range_km": 413,
      "power_kw": 132,
      "body_type": "suv",
      "drive": "rear",
      "seats": 5,

      "registration_year": 2021,
      "registration_month": 5,
      "manufacture_month": 3,
      "battery_warranty_km": 160000,

      "soh": 94,
      "soh_certificate_url": "https://partner.sk/cert/0457-soh.pdf",
      "soh_measurement_date": "2026-08-15",

      "color_exterior": "white",
      "metallic": true,
      "continuation_of_leasing": false,

      "branch": "Bratislava",
      "address": "Pestovateľská 5, Bratislava",
      "gps_lat": 48.1486,
      "gps_lng": 17.1077,
      "contact_phone": "+421 900 123 456",
      "contact_email": "bratislava@partner.sk",

      "title": "Škoda Enyaq iV 60, heat pump, first owner",
      "description": "Vehicle in perfect condition, first owner.",
      "condition": "used",
      "state": ["first-owner", "service-book"],
      "doors": 5,
      "equipment": ["heat-pump", "navigation", "adaptive-cruise-control", "panoramic-roof"],
      "equipment_unmapped": ["side airbags"],
      "price_without_vat": 17805
    }
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<feed>
  <vehicle>
    <!-- 3.1 REQUIRED -->
    <id>SK-2021-0457</id>
    <brand>Škoda</brand>
    <model>Enyaq</model>
    <price>21900</price>

    <!-- 3.2 NEEDED -->
    <photos>
      <photo>https://partner.sk/img/0457/1.jpg</photo>
      <photo>https://partner.sk/img/0457/2.jpg</photo>
    </photos>
    <status>active</status>
    <variant>iV 60</variant>
    <mileage_km>55279</mileage_km>
    <year_of_production>2021</year_of_production>
    <vat_deductible>1</vat_deductible>
    <currency>EUR</currency>

    <!-- 4 TECHNICAL DATA -->
    <catalog_id>14914</catalog_id>
    <vin>TMBJB7NY2NF022916</vin>
    <engine>iV 60 (RWD)</engine>
    <battery_kwh>62</battery_kwh>
    <wltp_range_km>413</wltp_range_km>
    <power_kw>132</power_kw>
    <body_type>suv</body_type>
    <drive>rear</drive>
    <seats>5</seats>

    <!-- 5.1 REGISTRATION AND WARRANTY -->
    <registration_year>2021</registration_year>
    <registration_month>5</registration_month>
    <manufacture_month>3</manufacture_month>
    <battery_warranty_km>160000</battery_warranty_km>

    <!-- 5.2 BATTERY -->
    <soh>94</soh>
    <soh_certificate_url>https://partner.sk/cert/0457-soh.pdf</soh_certificate_url>
    <soh_measurement_date>2026-08-15</soh_measurement_date>

    <!-- 5.3 APPEARANCE AND LEASING -->
    <color_exterior>white</color_exterior>
    <metallic>1</metallic>
    <continuation_of_leasing>0</continuation_of_leasing>

    <!-- 5.4 LOCATION AND CONTACT -->
    <branch>Bratislava</branch>
    <address>Pestovateľská 5, Bratislava</address>
    <gps_lat>48.1486</gps_lat>
    <gps_lng>17.1077</gps_lng>
    <contact_phone>+421 900 123 456</contact_phone>
    <contact_email>bratislava@partner.sk</contact_email>

    <!-- 5.5 LISTING CONTENT -->
    <title>Škoda Enyaq iV 60, heat pump, first owner</title>
    <description><![CDATA[Vehicle in perfect condition, first owner.]]></description>
    <condition>used</condition>
    <state>
      <item>first-owner</item>
      <item>service-book</item>
    </state>
    <doors>5</doors>
    <equipment>
      <item>heat-pump</item>
      <item>navigation</item>
      <item>adaptive-cruise-control</item>
      <item>panoramic-roof</item>
    </equipment>
    <equipment_unmapped>
      <item>side airbags</item>
    </equipment_unmapped>
    <price_without_vat>17805</price_without_vat>
  </vehicle>
</feed>

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

7. Checklist before sending

8. FAQ

9. Downloads

Together the two examples contain every field from part 1 and pass our import without a warning. The schemas check structure and types; what the import actually rejects is in 3.3.

Part 2 Our data for you (API) Catalog and value lists for mapping, your listings feed and the reconciliation feed

A1. Master data: overview and formats

Master data is a public export of our catalog and value lists: brands, models, versions per production year, equipment, colours and more, each with a stable ID and slug. Store them as your mapping key and send our values in the feed instead of free text. No token is needed.

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

• Format: ?format=json (default) or ?format=xml, or the header Accept: application/xml. Format, filters and pagination can be combined, for example ?brand=mini&year=2024&format=xml.
• Pagination (/catalog, A5, A6): ?page= and ?per_page=, 100 by default, at most 500 items per page.
• Envelope: paginated responses carry schema_version, generated_at, page, total_pages, total_items and items. /brands, /equipment and /enums return everything at once, with just schema_version, generated_at and items.

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

A2. Vehicle catalog (/catalog)

A catalog entry is one version in one production year, so a version built over several years has several entries. The mapping key is id; it never changes and you send it in the feed as catalog_id.

{
  "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": "type-2",
  "ev_type": "bev",
  "price_eur": 34990,
  "range_wltp": 310,
  "battery_kwh": 42.5,
  "battery_kwh_usable": 40.7,
  "power_kw": 135,
  "power_hp": 184,
  "battery_warranty_years": 8,
  "battery_warranty_km": 160000,
  "seats": 5,
  "detail_url": "https://nearcharger.sk/..."
}

• version is null for models with a single version; the identity is then make + model + year. Battery warranty is null when the manufacturer does not state it.
• battery_kwh is gross capacity (the same way we accept it in the feed), battery_kwh_usable the usable capacity. body_type, segment, drivetrain, charge_port and ev_type are slugs from /enums.
• seats is the catalog seat count. The same version is built with 5 or 7 seats, so send the actual count in your feed; your value takes precedence.

Filters: ?brand= takes a brand or model slug or ID exactly as in /brands (for example mini, 125, aceman or 704), ?year= a production year. Filters apply together and total_items reflects the filtered result. An unknown slug returns an empty list.

GET https://nearcharger.sk/wp-json/nearcharger/v1/master-data/catalog?brand=mini&year=2024

A3. Value lists (/brands, /equipment, /enums)

A value list item has a stable id, an English slug and names in three languages (cz is Czech). Send the slug in your feed: it is the same in every language.

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

If this document and an endpoint disagree on a value, the endpoint wins.

A4. Stability, updates and limits

• Updates: master data and the listings feed are generated once a night, around 03:30 UTC. One pull a day is enough, ideally after 04:00 UTC.
• Caching: responses carry ETag and Last-Modified. Send the ETag back in If-None-Match and an unchanged response returns 304 Not Modified without a body.
• Limits per IP address: 60 requests per minute across all master data endpoints, 30 per minute across the listings and reconciliation feeds. Above the limit you get 429.

A5. Your listings feed (token)

A private feed of your published listings, for example to check what is online or to sync into your system. It is protected by the token you receive at onboarding. Hidden listings are not in it; the reconciliation feed (A6) covers those. Formats and pagination as in A1.

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

Value list fields (color, condition, state, equipment, body_type, drivetrain, ev_type, market) contain slugs from A3; empty fields are null. The response carries Cache-Control: private, no-store, but a conditional request with If-None-Match still works and the token is verified before any 304.

{
  "id": 58153,
  "source_id": "BMWSK-000123",
  "url": "https://nearcharger.sk/inzerat/...",
  "title": "Mini Aceman E, 2024",
  "description": "Vehicle in perfect condition, first owner, service book.",
  "status": "active",
  "market": "sk",
  "updated_at": "2026-09-22T03:30:11+00:00",
  "car_version_id": 15498,
  "car_version_slug": "mini-aceman-e-2190",
  "make": "Mini",
  "model": "Aceman",
  "version": "E",
  "year": 2024,
  "manufacture_month": 1,
  "registration_year": 2024,
  "registration_month": 3,
  "price": { "amount": 34990, "currency": "EUR", "vat_deductible": true },
  "mileage_km": 12000,
  "soh": 95.9,
  "soh_certificate_url": "https://nearcharger.sk/wp-content/uploads/soh-certificate.pdf",
  "soh_measurement_date": "2026-08-14",
  "battery_kwh": 42.5,
  "range_wltp": 310,
  "battery_warranty_years": 8,
  "battery_warranty_km": 160000,
  "power_kw": 135,
  "body_type": "suv",
  "drivetrain": "front",
  "ev_type": "bev",
  "seats": 5,
  "color": "black",
  "doors": 5,
  "metallization": true,
  "continuation_of_leasing": false,
  "vin": "WMW21GF0XR2V15498",
  "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", "address": "Tuhovská 5, 831 07 Bratislava" },
  "contact": { "phone": "+421 900 123 456", "email": "sales@yourdomain.sk", "name": null, "address": null }
}

A6. Reconciliation feed: what happened to each vehicle (token)

One row for every vehicle you sent us, keyed on your id: our listing ID, URL, status and, for a vehicle that stayed out, the reason. It is not a nightly snapshot but the state right after the latest import run, so checking it once after each run is enough.

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

Same token, formats and pagination as the listings feed. In XML the root is <reconciliation>, rows are <items><item> and feeds <feeds><feed>. Caching works only through a content ETag (no Last-Modified). Until your feed is set up, the payload is empty (items: [], generated_at: null).

{
  "schema_version": 1,
  "generated_at": "2026-09-23T04:05:12Z",
  "partner_id": 29540,
  "feeds": [
    {
      "feed_id": 12,
      "name": "MINI Slovakia",
      "market": "sk",
      "is_active": true,
      "last_sync_at": "2026-09-23T04:00:00Z",
      "last_sync_status": "ok",
      "last_sync_message": "",
      "listings": { "live": 3, "sold": 1, "orphaned": 0, "error": 1, "over_cap": 0 }
    }
  ],
  "summary": { "error": 1, "sold": 1, "unmatched": 1, "published": 2 },
  "page": 1,
  "total_pages": 1,
  "total_items": 5,
  "items": [
    {
      "source_id": "MINI-SK-000101",
      "vin": "WMW11DJ0XP2R00101",
      "status": "published",
      "our_post_id": 58153,
      "url": "https://nearcharger.sk/inzerat/mini-cooper-se-2024/",
      "error_code": "",
      "error_message": "",
      "photos_sent": 12,
      "photos_imported": 12,
      "warnings": [],
      "car_version_id": 15344,
      "match_method": "catalog_id",
      "match_score": 1,
      "adopted_at": null,
      "sold_at": null,
      "orphaned_at": null,
      "last_seen_in_feed": "2026-09-23T04:00:41Z",
      "last_changed": "2026-09-21T04:00:37Z",
      "last_synced": "2026-09-23T04:00:41Z"
    },
    {
      "source_id": "MINI-SK-000105",
      "vin": "WMW11DJ0XP2R00105",
      "status": "error",
      "our_post_id": null,
      "url": null,
      "error_code": "validation",
      "error_message": "missing_required: price.amount",
      "photos_sent": null,
      "photos_imported": null,
      "warnings": [],
      "car_version_id": null,
      "match_method": "none",
      "match_score": null,
      "adopted_at": null,
      "sold_at": null,
      "orphaned_at": null,
      "last_seen_in_feed": "2026-09-23T04:00:41Z",
      "last_changed": null,
      "last_synced": "2026-09-23T04:00:41Z"
    }
  ]
}

A6.1 Statuses

Exactly one status per row; the first that applies wins (top to bottom).

A6.2 Error codes

A6.3 Warnings

A warning never changes the status; it only tells you what the listing is missing.

A6.4 Row fields and feed status