# Energy Bills FR OCR

Energy Bills FR API uses deep learning to automatically, accurately, and instantaneously parse your documents details. In a few seconds, the API extracts a set of data from your PDFs or photos of energy bills, including:

* Invoice Number
* Contract ID
* Delivery point
* Invoice date
* Due Date
* Total Before Taxes
* Total Taxes
* Total Amount
* Energy Supplier
* Energy Consumer
* Subscription
* Energy Usage
* Taxes and Contributions
* Meter Details

The Energy Bills FR OCR API supports documents from France. The energy bills from other nationalities and states are not supported with this model.

## Set up the API

{% hint style="info" %}
**Create an API key**

To begin using the Mindee V1 OCR API, your first step is to [create your V1 API key](https://docs.mindee.com/v1/get-started/create-api-key).
{% endhint %}

1. You'll need an energy bill. You can use one of the sample documents provided below.

Click here to download the [sample document](https://drive.google.com/file/d/1DIA6bSgFYAn3Lv31LpoGuWtwOp0MRDUg/view?usp=drive_link).

2. Access your Energy Bills FR API by clicking on the corresponding product card in the **Document Catalog**

   <figure><img src="https://126655343-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2al1MDqAP9Dg9iDRjkWg%2Fuploads%2Fgit-blob-15f68d972f5cfac8e9a1bbe553a111ca57a4edbd%2Fbc363381cacd365d9a8af9e738ea0458b8c7d8ebfd3cc55ca2e471668224c41e-image.png?alt=media" alt=""><figcaption></figcaption></figure>
3. From the left navigation, go to [**documentation**](https://docs.mindee.com/v1/platform-ui-tour/api-documentation) > API Reference, you'll find sample code in popular languages and command line.

{% tabs %}
{% tab title="Python" %}

{% endtab %}

{% tab title="undefined" %}

```python
from mindee import Client, product, AsyncPredictResponse

# Init a new client
mindee_client = Client(api_key="my-api-key-here")

# Load a file from disk
input_doc = mindee_client.source_from_path("/path/to/the/file.ext")

# Load a file from disk and enqueue it.
result: AsyncPredictResponse = mindee_client.enqueue_and_parse(
    product.fr.EnergyBillV1,
    input_doc,
)

# Print a brief summary of the parsed data
print(result.document)
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const mindee = require("mindee");
// for TS or modules:
// import * as mindee from "mindee";

// Init a new client
const mindeeClient = new mindee.v1.Client({ apiKey: "my-api-key-here" });

// Load a file from disk
const inputSource = mindeeClient.docFromPath("/path/to/the/file.ext");

// Parse the file
const apiResponse = mindeeClient.enqueueAndParse(
  mindee.v1.product.fr.EnergyBillV1,
  inputSource
);

// Handle the response Promise
apiResponse.then((resp) => {
  // print a string summary
  console.log(resp.document.toString());
});
```

{% endtab %}

{% tab title=".NET" %}

```csharp
using Mindee;
using Mindee.Input;
using Mindee.Product.Fr.EnergyBill;

string apiKey = "my-api-key-here";
string filePath = "/path/to/the/file.ext";

// Construct a new client
MindeeClient mindeeClient = new MindeeClient(apiKey);

// Load an input source as a path string
// Other input types can be used, as mentioned in the docs
var inputSource = new LocalInputSource(filePath);

// Call the product asynchronously with auto-polling
var response = await mindeeClient
    .EnqueueAndParseAsync<EnergyBillV1>(inputSource);

// Print a summary of all the predictions
System.Console.WriteLine(response.Document.ToString());

// Print only the document-level predictions
// System.Console.WriteLine(response.Document.Inference.Prediction.ToString());
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
#
# Install the Ruby client library by running:
# gem install mindee
#

require 'mindee'

# Init a new client
mindee_client = Mindee::Client.new(api_key: 'my-api-key')

# Load a file from disk
input_source = mindee_client.source_from_path('/path/to/the/file.ext')

# Parse the file
result = mindee_client.parse(
  input_source,
  Mindee::Product::FR::EnergyBill::EnergyBillV1
)

# Print a full summary of the parsed data in RST format
puts result.document

# Print the document-level parsed data
# puts result.document.inference.prediction
```

{% endtab %}

{% tab title="Java" %}

```java
import com.mindee.MindeeClient;
import com.mindee.input.LocalInputSource;
import com.mindee.parsing.common.AsyncPredictResponse;
import com.mindee.product.fr.energybill.EnergyBillV1;
import java.io.File;
import java.io.IOException;

public class SimpleMindeeClient {

  public static void main(String[] args) throws IOException, InterruptedException {
    String apiKey = "my-api-key-here";
    String filePath = "/path/to/the/file.ext";

    // Init a new client
    MindeeClient mindeeClient = new MindeeClient(apiKey);

    // Load a file from disk
    LocalInputSource inputSource = new LocalInputSource(new File(filePath));

    // Parse the file asynchronously
    AsyncPredictResponse<EnergyBillV1> response = mindeeClient.enqueueAndParse(
        EnergyBillV1.class,
        inputSource
    );

    // Print a summary of the response
    System.out.println(response.toString());

    // Print a summary of the predictions
//  System.out.println(response.getDocumentObj().toString());

    // Print the document-level predictions
//    System.out.println(response.getDocumentObj().getInference().getPrediction().toString());

    // Print the page-level predictions
//    response.getDocumentObj().getInference().getPages().forEach(
//        page -> System.out.println(page.toString())
//    );
  }

}
```

{% endtab %}

{% tab title="Bash" %}

```bash
API_KEY='my-api-key-here'
ACCOUNT='mindee'
ENDPOINT='energy_bill_fra'
VERSION='1'
FILE_PATH='/path/to/your/file.png'

# Maximum amount of retries to get the result of a queue
MAX_RETRIES=10

# Delay between requests
DELAY=6

# Enqueue the document for async parsing
QUEUE_RESULT=$(curl -sS --request POST \
  -H "Authorization: Token $API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "document=@$FILE_PATH" \
  "https://api.mindee.net/v1/products/$ACCOUNT/$ENDPOINT/v$VERSION/predict_async")

# Status code sent back from the server
STATUS_CODE=$(echo "$QUEUE_RESULT" | grep -oP "[\"|']status_code[\"|']:[\s][\"|']*[a-zA-Z0-9-]*" | rev | cut --complement -f2- -d" " | rev)

# Check that the document was properly queued
if [ -z "$STATUS_CODE" ] || [ "$STATUS_CODE" -gt 399 ] || [ "$STATUS_CODE" -lt 200 ]
then
  if [ -z "$STATUS_CODE" ]
  then
    echo "Request couldn't be processed."
    exit 1
  fi
  echo "Error $STATUS_CODE was returned by API during enqueuing. "

  # Print the additional details, if there are any:
  ERROR=$(echo "$QUEUE_RESULT" | grep -oP "[\"|']error[\"|']:[\s]\{[^\}]*" | rev | cut --complement -f2- -d"{" | rev)
  if [ -z "$ERROR" ]
  then
    exit 1
  fi

  # Details on the potential error:
  ERROR_CODE=$(echo "$ERROR" | grep -oP "[\"|']code[\"|']:[\s]\"[^(\"|\')]*" | rev | cut --complement -f2- -d"\"" | rev)
  MESSAGE=$(echo "$QUEUE_RESULT" | grep -oP "[\"|']message[\"|']:[\s]\"[^(\"|\')]*" | rev | cut --complement -f2- -d"\"" | rev)
  DETAILS=$(echo "$QUEUE_RESULT" | grep -oP "[\"|']details[\"|']:[\s]\"[^(\"|\')]*" | rev | cut --complement -f2- -d"\"" | rev)
  echo "This was the given explanation:"
  echo "-------------------------"
  echo "Error Code: $ERROR_CODE"
  echo "Message: $MESSAGE"
  echo "Details: $DETAILS"
  echo "-------------------------"
  exit 1
else

  echo "File sent, starting to retrieve from server..."

  # Get the document's queue ID
  QUEUE_ID=$(echo "$QUEUE_RESULT" | grep -oP "[\"|']id[\"|']:[\s][\"|'][a-zA-Z0-9-]*" | rev | cut --complement -f2- -d"\"" | rev)

  # Amount of attempts to retrieve the parsed document were made
  TIMES_TRIED=1

  # Try to fetch the file until we get it, or until we hit the maximum amount of retries
  while [ "$TIMES_TRIED" -lt "$MAX_RETRIES" ]
  do
    # Wait for a bit at each step
    sleep $DELAY

    # Note: we use -L here because the location of the file might be behind a redirection
    PARSED_RESULT=$(curl -sS -L \
      -H "Authorization: Token $API_KEY" \
      "https://api.mindee.net/v1/products/$ACCOUNT/$ENDPOINT/v$VERSION/documents/queue/$QUEUE_ID")

    # Isolating the job (queue) & the status to monitor the document
    JOB=$(echo "$PARSED_RESULT" | grep -ioP "[\"|']job[\"|']:[\s]\{[^\}]*" | rev | cut --complement -f2- -d"{" | rev)
    QUEUE_STATUS=$(echo "$JOB" | grep -ioP "[\"|']status[\"|']:[\s][\"|'][a-zA-Z0-9-]*" | rev | cut --complement -f2- -d"\"" | rev)
    if [ "$QUEUE_STATUS" = "completed" ]
    then
      # Print the result
      echo "$PARSED_RESULT"

      # Optional: isolate the document:
      # DOCUMENT=$(echo "$PARSED_RESULT" | grep -ioP "[\"|']document[\"|']:[\s].*([\"|']job[\"|'])" | rev | cut -f2- -d"," | rev)
      # echo "{$DOCUMENT}"

      # Remark: on compatible shells, fields can also be extracted through the use of tools like jq:
      # DOCUMENT=$(echo "$PARSED_RESULT" | jq '.["document"]')
      exit 0
    fi
    TIMES_TRIED=$((TIMES_TRIED+1))
  done
fi

echo "Operation aborted, document not retrieved after $TIMES_TRIED tries"
exit 1
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

use Mindee\Client;
use Mindee\Product\Fr\EnergyBill\EnergyBillV1;

// Init a new client
$mindeeClient = new Client("my-api-key-here");

// Load a file from disk
$inputSource = $mindeeClient->sourceFromPath("/path/to/the/file.ext");

// Parse the file asynchronously
$apiResponse = $mindeeClient->enqueueAndParse(EnergyBillV1::class, $inputSource);

echo $apiResponse->document;
```

{% endtab %}
{% endtabs %}

* Replace **my-api-key-here** with your new API key, or use the **select an API key** feature and it will be filled automatically.
* Copy and paste the sample code of your desired choice in your application, code environment, terminal etc.
* Replace `/path/to/the/file.ext` with the path to your input document.

{% hint style="warning" %}
Remember to replace with your V1 API key.
{% endhint %}

4. Run your code. You will receive a JSON response with document details.

## API Response

Here is the full JSON response you get when you call the API:

```json
{
  "api_request": {
    "error": {},
    "resources": [
      "document",
      "job"
    ],
    "status": "success",
    "status_code": 200,
    "url": "https://api.mindee.net/v1/products/mindee/energy_bill_fra/v1/documents/344a611f-b9f4-4cbb-aaad-b904896a63bf"
  },
  "document": {
    "id": "344a611f-b9f4-4cbb-aaad-b904896a63bf",
    "inference": {
      "extras": {},
      "finished_at": "2024-10-28T14:09:44.641000",
      "is_rotation_applied": true,
      "pages": [
        {
          "extras": {},
          "id": 0,
          "orientation": {
            "value": 0
          },
          "prediction": {}
        },
        {
          "extras": {},
          "id": 1,
          "orientation": {
            "value": 0
          },
          "prediction": {}
        },
        {
          "extras": {},
          "id": 2,
          "orientation": {
            "value": 0
          },
          "prediction": {}
        }
      ],
      "prediction": {
        "contract_id": {
          "value": "1234567890"
        },
        "delivery_point": {
          "value": "98765432109876"
        },
        "due_date": {
          "value": "2021-02-15"
        },
        "energy_consumer": {
          "address": "12 AVENUE DES RÊVES, RDC A 123 COUR FAUSSE A, 75000 PARIS",
          "name": "JOHN DOE"
        },
        "energy_supplier": {
          "address": "TSA 12345, 12345 DEMOCITY CEDEX",
          "name": "EDF"
        },
        "energy_usage": [
          {
            "description": "Electricité Période unique",
            "end_date": "2021-01-27",
            "start_date": "2020-11-28",
            "tax_rate": 20,
            "total": 898.43,
            "unit_price": 0.1047
          }
        ],
        "invoice_date": {
          "value": "2021-01-29"
        },
        "invoice_number": {
          "value": "1234567890"
        },
        "meter_details": {
          "meter_number": "620",
          "meter_type": "electricity",
          "unit": "kW"
        },
        "subscription": [
          {
            "description": "Abonnement électricité",
            "end_date": "2021-02-28",
            "start_date": "2021-01-01",
            "tax_rate": 5.5,
            "total": 59,
            "unit_price": 29.5
          }
        ],
        "taxes_and_contributions": [
          {
            "description": "Contribution au Service Public de l'Electricité",
            "end_date": "2021-01-27",
            "start_date": "2020-11-28",
            "tax_rate": 20,
            "total": 193.07,
            "unit_price": 0.0225
          },
          {
            "description": "Taxe Départementale sur la Conso Finale Electricité",
            "end_date": "2020-12-31",
            "start_date": "2020-11-28",
            "tax_rate": 20,
            "total": 14.28,
            "unit_price": 0.003275
          },
          {
            "description": "Taxe Départementale sur la Conso Finale Electricité",
            "end_date": "2021-01-27",
            "start_date": "2021-01-01",
            "tax_rate": 20,
            "total": 13.98,
            "unit_price": 0.003315
          },
          {
            "description": "Taxe Communale sur la Conso Finale Electricité",
            "end_date": "2020-12-31",
            "start_date": "2020-11-28",
            "tax_rate": 20,
            "total": 28.56,
            "unit_price": 0.006545
          },
          {
            "description": "Taxe Communale sur la Conso Finale Electricité",
            "end_date": "2021-01-27",
            "start_date": "2021-01-01",
            "tax_rate": 20,
            "total": 27.96,
            "unit_price": 0.00663
          },
          {
            "description": "Contribution Tarifaire d'Acheminement",
            "end_date": "2020-12-28",
            "start_date": "2020-11-28",
            "tax_rate": 5.5,
            "total": 21.25,
            "unit_price": 21.25
          }
        ],
        "total_amount": {
          "value": 1479.85
        },
        "total_before_taxes": {
          "value": 1241.03
        },
        "total_taxes": {
          "value": 238.82
        }
      },
      "processing_time": 14.709,
      "product": {
        "features": [
          "invoice_number",
          "contract_id",
          "delivery_point",
          "invoice_date",
          "due_date",
          "total_before_taxes",
          "total_taxes",
          "total_amount",
          "energy_supplier",
          "energy_consumer",
          "subscription",
          "energy_usage",
          "taxes_and_contributions",
          "meter_details"
        ],
        "name": "mindee/energy_bill_fra",
        "type": "standard",
        "version": "1.0"
      },
      "started_at": "2024-10-28T14:09:29.711000"
    },
    "n_pages": 3,
    "name": "default_sample.pdf"
  },
  "job": {
    "available_at": "2024-10-28T14:09:44.655000",
    "error": {},
    "id": "b07cc034-fe08-45ee-a249-01ceb412f615",
    "issued_at": "2024-10-28T14:09:29.711000",
    "status": "completed"
  }
}
```

You can find the prediction within the `prediction` key found in **`document > inference > prediction` for document-level predictions**: it contains the different fields extracted at the document level, meaning that for multi-pages PDFs, we reconstruct a single object using all the pages.

## Detailed Field Information

Using the above document example the following are the basic fields that can be extracted.

* [Invoice Number](#invoice-number)
* [Contract ID](#contract-id)
* [Delivery point](#delivery-point)
* [Invoice date](#invoice-date)
* [Due Date](#due-date)
* [Total Before Taxes](#total-before-taxes)
* [Total Taxes](#total-taxes)
* [Total Amount](#total-amount)
* [Energy Supplier](#energy-supplier)
* [Energy Consumer](#energy-consumer)
* [Subscription](#subscription)
* [Energy Usage](#ernergy-usage)
* [Taxes and Contributions](#taxes-and-contributions)
* [Meter Details](#meter-details)

### Invoice Number

* **invoice\_number**: The unique identifier of the energy bill.

```json
{
  "invoice_number": {
    "value": "1234567890"
  }
}
```

### Contract ID

* **contract\_id**: The unique identifier associated with a specific contract.

```json
{
  "contract_id": {
    "value": "1234567890"
  }
}
```

### Delivery Point

* **delivery\_point**: The unique identifier assigned to each electricity or gas consumption point. It specifies the exact location where the energy is delivered

```json
{
  "delivery_point": {
    "value": "98765432109876"
  }
}
```

### Invoice Date

* **invoice\_date**: The date when the energy invoice was issued.

```json
{
  "invoice_date": {
    "value": "2021-01-29"
  }
}
```

### Due Date

* **due\_date**: The date by which the payment for the energy invoice is due.

```json
{
  "due_date": {
    "value":"2021-02-15"
  }
}
```

### Total Before Taxes

* **total\_before\_taxes**: The total amount to be paid for the energy invoice before taxes.

```json
{
  "total_before_taxes": {
    "value": 1241.03
  }
}
```

### Total Taxes

* **total\_taxes**: Total of taxes applied to the invoice.

```json
{
  "total_taxes": {
    "value": 238.82
  }
}
```

### Total Amount

* **total\_amount**: The total amount to be paid for the energy invoice.

```json
{
  "total_amount": {
    "value": 1479.85
  }
}
```

### Energy Supplier

* **energy\_supplier**: The company that supplies the energy.
  * **name**: The name of the energy supplier.
  * **address**: The address of the energy supplier.

```json
{
  "energy_supplier": {
    "address": "TSA 12345, 12345 DEMOCITY CEDEX",
    "name": "EDF"
  }
}
```

### Energy Consumer

* **energy\_consumer**: The entity that consumes the energy.
  * **name**: The name of the energy consumer.
  * **address**: The address of the energy consumer.

```json
{
  "**energy_consumer**": {
    "address": "12 AVENUE DES RÊVES, RDC A 123 COUR FAUSSE A, 75000 PARIS",
    "name": "JOHN DOE"
  }
}
```

### Subscription

* **subscription**: The subscription details fee for the energy service.
  * **description**: Description or details of the subscription.
  * **start\_date**: The start date of the subscription.
  * **end\_date**: The end date of the subscription.
  * **unit\_price**: The price per unit of subscription.
  * **total**: The total cost of subscription.
  * **tax\_rate**: The rate of tax applied to the total cost.

```json
{
  "subscription": [
    {
      "description": "Abonnement électricité",
      "end_date": "2021-02-28",
      "start_date": "2021-01-01",
      "tax_rate": 5.5,
      "total": 59,
      "unit_price": 29.5
    }
  ]
}
```

### Energy Usage

* **energy\_usage**: Details of energy consumption.
  * **description**: Description or details of the energy usage.
  * **start\_date**: The start date of the energy usage.
  * **end\_date**: The end date of the energy usage.
  * **unit\_price**: The price per unit of energy consumed.
  * **total**: The total cost of energy consumed.
  * **tax\_rate**: The rate of tax applied to the total cost.

```json
{
  "energy_usage": [
    {
      "description": "Electricité Période unique",
      "end_date": "2021-01-27",
      "start_date": "2020-11-28",
      "tax_rate": 20,
      "total": 898.43,
      "unit_price":  0.1047
    }
  ]
}
```

### Taxes and Contributions

* **taxes\_and\_contributions**: Details of Taxes and Contributions.
  * **description**: Description or details of the Taxes and Contributions.
  * **start\_date**: The start date of the Taxes and Contributions.
  * **end\_date**: The end date of the Taxes and Contributions.
  * **unit\_price**: The price per unit of Taxes and Contributions.
  * **total**: The total cost of Taxes and Contributions.
  * **tax\_rate**: The rate of tax applied to the total cost.

```json
{
  "taxes_and_contributions": [
    {
      "description": "Contribution au Service Public de l'Electricité",
      "end_date": "2021-01-27",
      "start_date": "2020-11-28",
      "tax_rate": 20,
      "total": 193.07,
      "unit_price": 0.0225
    },
    {
      "description": "Taxe Départementale sur la Conso Finale Electricité",
      "end_date": "2020-12-31",
      "start_date": "2020-11-28",
      "tax_rate": 20,
      "total": 14.28,
      "unit_price": 0.003275
    },
    {
      "description": "Taxe Départementale sur la Conso Finale Electricité",
      "end_date": "2021-01-27",
      "start_date": "2021-01-01",
      "tax_rate": 20,
      "total": 13.98,
      "unit_price": 0.003315
    },
    {
      "description": "Taxe Communale sur la Conso Finale Electricité",
      "end_date": "2020-12-31",
      "start_date": "2020-11-28",
      "tax_rate": 20,
      "total": 28.56,
      "unit_price": 0.006545
    },
    {
      "description": "Taxe Communale sur la Conso Finale Electricité",
      "end_date": "2021-01-27",
      "start_date": "2021-01-01",
      "tax_rate": 20,
      "total": 27.96,
      "unit_price": 0.00663
    },
    {
      "description": "Contribution Tarifaire d'Acheminement",
      "end_date": "2020-12-28",
      "start_date": "2020-11-28",
      "tax_rate": 5.5,
      "total": 21.25,
      "unit_price": 21.25
    }
  ]
}
```

### Meter Details

* **meter\_details**: Information about the energy meter.
  * meter\_number: The unique identifier of the energy meter.
  * meter\_type: The type of energy meter.
  * type: The unit of measurement for energy consumption, which can be kW, m³, or L.

```json
{
  "meter_details": {
    "meter_number": "620",
    "meter_type": "electricity",
    "unit": "kW"
  }
}
```