> For the complete documentation index, see [llms.txt](https://motorweb.gitbook.io/motorweb/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://motorweb.gitbook.io/motorweb/additional-services/fuel-economy-labels.md).

# Fuel Economy Labels

Government fuel economy label data and images for a vehicle.

Two endpoints. One returns the label data as XML, the other returns the label as a PNG image ready to display or print.

Both work against a vehicle that already exists in MotorWeb under your account. Neither accepts a plate or VIN.

### **Environments**

<table><thead><tr><th width="214" align="center">Environment</th><th>Base URL</th></tr></thead><tbody><tr><td align="center">UAT</td><td><code>https://robot.uat.motorweb.co.nz</code></td></tr><tr><td align="center">Production</td><td><code>https://robot.motorweb.co.nz</code></td></tr></tbody></table>

### **Endpoints**

<table><thead><tr><th width="380">Path</th><th width="120" align="center">Version</th><th>Returns</th></tr></thead><tbody><tr><td><code>/action/robotFuelEconomyLabel/{version}</code></td><td align="center">1.0</td><td><code>text/xml</code></td></tr><tr><td><code>/action/robotFuelEconomyLabelRender/{version}</code></td><td align="center">1.0</td><td><code>image/png</code></td></tr></tbody></table>

### **Access**

No specific privilege is required.

### **Headers**

No request headers are required.

### **Body**

```
< no body required >
```

### **Query Parameters**

<table><thead><tr><th width="180">Name</th><th>Value</th></tr></thead><tbody><tr><td><code>vehicleId</code></td><td>The ID of a vehicle already held under your account. Required unless you supply <code>stockNumber</code>.</td></tr><tr><td><code>stockNumber</code></td><td>Your own reference for a vehicle already held under your account.</td></tr><tr><td><code>width</code></td><td>Render endpoint only. Image width in pixels. Defaults to <code>680</code>. Maximum <code>1500</code>.</td></tr></tbody></table>

{% hint style="warning" %}
Neither endpoint accepts `plateOrVin`. Generate a vehicle report first, take the `vehicle-id` from the response, then call these endpoints with it.
{% endhint %}

### **Response**

{% tabs %}
{% tab title="200 Label available" %}

```xml
<fuel-economy-label version="1.0" vehicle-id="-285694250" billing-user="MotorWeb Development" id="-285694780" reference="19c7e2b4" timestamp="2025-04-02T15:20:11.442" user="MotorWeb Development">
    <Explanation>Fuel economy information is available for this vehicle.</Explanation>
    <LabelVersion>2023</LabelVersion>
    <LabelID>FEL-2023-004821</LabelID>
    <Make>Mitsubishi</Make>
    <Model>ASX</Model>
    <SubModel>2WD 2.0P CVT Sport</SubModel>
    <FuelStars>4</FuelStars>
    <FuelConsumption>8.8</FuelConsumption>
    <YearlyCost>2640</YearlyCost>
</fuel-economy-label>
```

{% endtab %}

{% tab title="200 No label available" %}

```xml
<fuel-economy-label version="1.0" vehicle-id="-285694251" billing-user="MotorWeb Development" id="-285694781" reference="7a03cd91" timestamp="2025-04-02T15:23:56.108" user="MotorWeb Development">
    <Explanation>No Government fuel economy information is available for this vehicle.</Explanation>
    <LabelID>FEL-NONE</LabelID>
</fuel-economy-label>
```

{% endtab %}

{% tab title="200 PNG" %}
The render endpoint returns a lossless PNG image with `Content-Type: image/png`.

Responses carry an `Expires` header set 12 hours ahead. There is no `Cache-Control` header, so some clients will not cache them.
{% endtab %}

{% tab title="400" %}

```
No Government fuel economy information for this vehicle
```

or

```
This vehicle does not have the identifiers applicable to retrieve a fuel economy label
```

or

```
Requested width too wide (more than 1500)
```

{% endtab %}
{% endtabs %}

### **Fields**

<table><thead><tr><th width="200">Element</th><th>Description</th></tr></thead><tbody><tr><td><code>Explanation</code></td><td>Always present. When no label is available, this holds the reason.</td></tr><tr><td><code>LabelID</code></td><td>Always present. Use it as the reference on the label.</td></tr><tr><td><code>LabelVersion</code></td><td>Optional. The label design version.</td></tr><tr><td><code>FuelStars</code></td><td>Optional. An integer from <code>0</code> to <code>12</code>. <strong>Divide by 2 to get the star rating</strong>, because half stars exist. The maximum is 6 stars, which is a value of 12.</td></tr><tr><td><code>FuelConsumption</code></td><td>Optional. Litres per 100 kilometres.</td></tr><tr><td><code>YearlyCost</code></td><td>Optional. Estimated annual fuel cost.</td></tr><tr><td><code>Make</code>, <code>Model</code>, <code>SubModel</code></td><td>Optional. The vehicle the label applies to.</td></tr></tbody></table>

{% hint style="warning" %}
**`FuelStars` absent means no label.**

When `FuelStars` is missing, no fuel economy label exists for this vehicle. Read `Explanation` for the reason. Do not treat a missing value as zero stars.
{% endhint %}

### **XSD**

{% embed url="<https://www.motorweb.co.nz/action/robotSchema/fuel-economy-label-1.0.xsd>" %}

### **Errors**

Errors return `text/plain` with the message in the body. A `MotorWeb-Error-Code` response header carries a machine-readable code.

<table><thead><tr><th width="80">HTTP</th><th width="180">Error code header</th><th>Message and cause</th></tr></thead><tbody><tr><td>400</td><td><code>NO-FUEL</code></td><td>There is no Government fuel economy information for this vehicle.</td></tr><tr><td>400</td><td><code>BAD-VEHICLE</code></td><td><code>This vehicle does not have the identifiers applicable to retrieve a fuel economy label</code></td></tr><tr><td>400</td><td><code>BAD-PARAM</code></td><td><code>No search specified</code> — supply <code>vehicleId</code> or <code>stockNumber</code>.</td></tr><tr><td>400</td><td><code>BAD-PARAM</code></td><td><code>Requested width too wide (more than 1500)</code> — render endpoint only.</td></tr><tr><td>400</td><td><code>NO-MATCH</code></td><td><code>Transaction has no FuelSaver information</code> — render endpoint only.</td></tr><tr><td>400</td><td><code>EXTERNAL-ISSUE</code></td><td>The fuel economy service is unreachable and no cached label exists.</td></tr><tr><td>401</td><td>—</td><td>Certificate authentication failed.</td></tr></tbody></table>

**Example cURL command:**

```bash
# Label data as XML
curl --cert-type P12 --cert motorwebnz.p12:<CERTPASSWORD> \
  "https://robot.motorweb.co.nz/action/robotFuelEconomyLabel/1.0?vehicleId=-285694250"

# Label image at default width
curl --cert-type P12 --cert motorwebnz.p12:<CERTPASSWORD> \
  "https://robot.motorweb.co.nz/action/robotFuelEconomyLabelRender/1.0?vehicleId=-285694250" \
  --output label.png

# Label image at a specific width
curl --cert-type P12 --cert motorwebnz.p12:<CERTPASSWORD> \
  "https://robot.motorweb.co.nz/action/robotFuelEconomyLabelRender/1.0?vehicleId=-285694250&width=1200" \
  --output label.png
```

**Notes:**

* Authentication is mutual TLS with a MotorWeb-issued client certificate
* Both endpoints need an existing vehicle. Neither accepts a plate or VIN
* Divide `FuelStars` by 2 to get the star rating
* Rendered images carry a 12 hour `Expires` header, but no `Cache-Control`
* [VIR](/motorweb/motorweb-reports/vir.md) and [Asset Check](/motorweb/motorweb-reports/asset-check.md) can return a `fuel-economy-label` element inline, which avoids a second call