Energy Bills FR OCR
Automatically extract data from French energy bills
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
Before making any API calls, you need to have created your API key.
- You'll need an energy bills. You can use one of the sample documents provided below.
Click here to download the sample document.
- Access your Energy Bills FR API by clicking on the corresponding product card in the Document Catalog
- From the left navigation, go to documentation > API Reference, you'll find sample code in popular languages and command line.
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)
const mindee = require("mindee");
// for TS or modules:
// import * as mindee from "mindee";
// Init a new client
const mindeeClient = new mindee.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.product.fr.EnergyBillV1,
inputSource
);
// Handle the response Promise
apiResponse.then((resp) => {
// print a string summary
console.log(resp.document.toString());
});
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());
require 'mindee'
# Init a new client
mindee_client = Mindee::Client.new(api_key: 'my-api-key-here')
# Load a file from disk
input_source = mindee_client.source_from_path('/path/to/the/file.ext')
# Parse the file
result = mindee_client.enqueue_and_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
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())
// );
}
}
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
<?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;
- 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 or terminal.
- Replace
/path/to/my/file
with the path to your document.
Always remember to replace your API key!
- 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:
{
"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.
Extracted data
Using the above document example the following are the basic fields that can be extracted.
- 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
Invoice Number
- invoice_number: The unique identifier of the energy bill.
{
"invoice_number": {
"value": "1234567890"
}
}
Contract ID
- contract_id: The unique identifier associated with a specific contract.
{
"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
{
"delivery_point": {
"value": "98765432109876"
}
}
Invoice Date
- invoice_date: The date when the energy invoice was issued.
{
"invoice_date": {
"value": "2021-01-29"
}
}
Due Date
- due_date: The date by which the payment for the energy invoice is due.
{
"due_date": {
"value":"2021-02-15"
}
}
Total Before Taxes
- total_before_taxes: The total amount to be paid for the energy invoice before taxes.
{
"total_before_taxes": {
"value": 1241.03
}
}
Total Taxes
- total_taxes: Total of taxes applied to the invoice.
{
"total_taxes": {
"value": 238.82
}
}
Total Amount
- total_amount: The total amount to be paid for the energy invoice.
{
"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.
{
"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.
{
"**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.
{
"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.
{
"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.
{
"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.
{
"meter_details": {
"meter_number": "620",
"meter_type": "electricity",
"unit": "kW"
}
}
Questions?
Join our Slack
Updated about 2 months ago