Incubator

The incubator Gini API is unstable and subject of change. It allows early access to immature features which are still in research or under development.

Incubating Extractions

This kind of features are not accessible via the v1 version of the Gini API. They are only accessible by submitting the incubator version header and/or special parameters.

Accessing Incubating Extractions

The incubating extractions are accessible by submitting the incubator custom media type Access header. See the example below:

curl -H 'Authorization: BEARER <token>' -H 'Accept: application/vnd.gini.incubator+json' -i https://api.gini.net/documents/<documentId>/extractions

Receipt Extraction

Receipts are printed acknowledgements that a specified article or payment has been received. They are often printed in stores with cash registers and include information like price, tax, discount and the purchased items or services.

Supported Specific Extractions

Name Description Entity Candidates Special Values
amountToPay The amount which was paid. amount n/a n/a
docType The document type of a given document. doctype n/a Receipt
documentDate The document date. date dates n/a
documentTime The document time. time times n/a
email The email of the seller. email emails n/a
netAmount The net amount on the receipt. amount netAmounts n/a
phoneNumber The phone number of the seller. phonenumber phoneNumbers n/a
receiptNumber The number of the receipt. invoiceid receiptNumbers n/a
senderName The name of the seller. companyname senderNames n/a
senderNameAddition The name of the branch of the seller. companynameaddition n/a n/a
senderStreet The street and house number of the seller. street n/a n/a
senderPostalCode The zip code of the seller. zipcode n/a n/a
senderCity The city of the seller. city n/a n/a
taxNumber The tax number of the seller. taxnumber taxNumbers n/a
vatRegNumber The vat identification number of the seller. vat vatRegNumbers n/a
website The website of the seller. url websites n/a

Submit

The document type hint parameter must be set to Receipt when Submitting files. See the example below:

curl -H 'Authorization: BEARER <token>' --data-binary '@file.pdf' -H 'Accept: application/vnd.gini.v1+json' -i https://api.gini.net/documents?filename=file.pdf&doctype=Receipt

Fuel Receipt Extraction

Fuel receipts are a special kind of receipts for purchasing gasoline in a gas station.

Supported Specific Extractions

Name Description Entity Candidates Special Values
amountLiters The amount of gasoline purchased. volume n/a n/a
amountToPay The amount which was paid. amount n/a n/a
docType The document type of a given document. doctype n/a FuelReceipt
pricePerLiter The price per liter of gasoline. fuelprice pricePerLiters n/a

Submit

The document type hint parameter must be set to FuelReceipt when Submitting files. See the example below:

curl -H 'Authorization: BEARER <token>' --data-binary '@file.pdf' -H 'Accept: application/vnd.gini.v1+json' -i https://api.gini.net/documents?filename=file.pdf&doctype=FuelReceipt

Access

Furthermore, the Accept header must be set to the incubator custom media type if you access the extractions. See Accessing Incubating Extractions

Subject Extraction

This extraction captures the subject line of a letter.

Supported Specific Extractions

Name Description Entity Candidates Special Values
subject The subject line of a letter. subject n/a n/a

Access

The Accept header must be set to the incubator custom media type if you access the extractions. See Accessing Incubating Extractions

Recipient Extraction

This extraction captures the recipient of a letter.

Supported Specific Extractions

Name Description Entity Candidates Special Values
recipient The recipient of a letter. recipient n/a n/a

Access

The Accept header must be set to the incubator custom media type if you access the extractions. See Accessing Incubating Extractions

Energy Statement Extractions

An energy statement is a document sent by an energy provider to their client which lists the energy consumption over a certain time period together with the charges.

Supported Specific Extractions

Name Description Entity Candidates Special Values
amountToPay The amount which has to be paid amount n/a n/a
billingAmount The amount which was charged. amount n/a n/a
consumption The amount of energy which was consumed. energyconsumption consumptions n/a
consumptionDuration The time period of the charged consumption. timeperiod n/a n/a
counterNumber The number of the counter which measured the consumption. counternumber counterNumbers n/a
customerPostalCode The postal code of the client. postalcode n/a n/a
docType The document type of a given document. doctype n/a Energy
energyType The type of energy being charged. energytype n/a Electricity, Gas
paidAmount The amount which was already paid. amount n/a n/a
refundAmount The amount which will be refunded. amount n/a n/a

Submit

The document type hint parameter must be set to Energy when Submitting files. See the example below:

curl -H 'Authorization: BEARER <token>' --data-binary '@file.pdf' -H 'Accept: application/vnd.gini.v1+json' -i https://api.gini.net/documents?filename=file.pdf&doctype=Energy

Access

Furthermore, the Accept header must be set to the incubator custom media type if you access the extractions. See Accessing Incubating Extractions

Incubating Entities

volume

Describes a volume (e.g. of gasoline) with a specific unit (e.g. liter) in the format <Volume>:<Unit>, where <Volume> is a decimal number with ”.” as decimal separator and ”:” as delimiter between <Volume> and <Unit>.

Format

Name Type Description
entity string Must be volume
value string Volume in the defined format
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "volume",
    "value": "63.56:l",
    "box": {
        "top": 210.0,
        "left": 199.0,
        "width": 43.0,
        "height": 7.0,
        "page": 1
    }
}

fuelprice

Describes a price per liter (e.g. of gasoline) with a specific currency (e.g. EUR) in the format <Fuelprice>:<Currency>, where <Fuelprice> is a decimal number with ”.” as decimal separator and ”:” as delimiter between <Fuelprice> and <Currency>.

Format

Name Type Description
entity string Must be fuelprice
value string Fuelprice in the defined format
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "fuelprice",
    "value": "1.439:EUR",
    "box": {
        "top": 210.0,
        "left": 257.0,
        "width": 53.0,
        "height": 8.0,
        "page": 1
    }
}

subject

Represents the subject line of a letter.

Format

Name Type Description
entity string Must be subject
value string The subject
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "subject",
    "value": "Thema Unser Vorteilsangebot. Ihre Fahrfreude.",
    "box": {
        "top": 379.0,
        "left": 68.0,
        "width": 244.0,
        "height": 10.0,
        "page": 1
    }
}

recipient

Represents the recipient of a letter.

Format

Name Type Description
entity string Must be recipient
value string The recipient
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "recipient",
    "value": "Max Mustermann Musterstrasse 1 Musterstadt",
    "box": {
        "top": 379.0,
        "left": 68.0,
        "width": 244.0,
        "height": 10.0,
        "page": 1
    }
}

counternumber

Represents the number of a counter which measures energy consumption.

Format

Name Type Description
entity string Must be counternumber
value string The counter number.
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "counternumber",
    "value": "220666",
    "box": {
        "top": 379.0,
        "left": 68.0,
        "width": 244.0,
        "height": 10.0,
        "page": 1
    }
}

energyconsumption

Represents the amount of consumed energy. The format is <amount>:<unit> where <unit> is always kWh.

Format

Name Type Description
entity string Must be energyconsumption
value string The energy consumption in the defined format.
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "energyconsumption",
    "value": "176.00:kWh",
    "box": {
        "top": 379.0,
        "left": 68.0,
        "width": 244.0,
        "height": 10.0,
        "page": 1
    }
}

energytype

Represents the type of energy beeing charged. The possible types are Electricity or Gas.

Format

Name Type Description
entity string Must be energytype
value string Electricity or Gas
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "energytype",
    "value": "Gas",
    "box": {
        "top": 379.0,
        "left": 68.0,
        "width": 244.0,
        "height": 10.0,
        "page": 1
    }
}

postalcode

Represents a postal code. The format is <countrycode>:<zipcode>:<city>.

Format

Name Type Description
entity string Must be postalcode
value string The postalcode in the defined format.
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "postalcode",
    "value": "DE:81379:Munich",
    "box": {
        "top": 379.0,
        "left": 68.0,
        "width": 244.0,
        "height": 10.0,
        "page": 1
    }
}

timeperiod

Represents a time period. The format is <number of days>:day.

Format

Name Type Description
entity string Must be timeperiod
value string The timeperiod in the defined format.
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "timeperiod",
    "value": "30:day",
    "box": {
        "top": 379.0,
        "left": 68.0,
        "width": 244.0,
        "height": 10.0,
        "page": 1
    }
}

time

Describes a time in the format <hour>:<minute>:<second> with ”:” as delimiter between time components.

Format

Name Type Description
entity string Must be time
value string Time in the defined format
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "time",
    "value": "12:13:14",
    "box": {
        "page": 1,
        "left": 429.0,
        "top": 143.0,
        "width": 40.0,
        "height": 8.0
    }
}