# US Mail OCR Mindee’s US Mail OCR 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 US mails, including: * Sender Name * Sender Address * Recipient Names * Recipient Addresses The US Mail OCR API supports documents from the US. The documents 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. To test your API, you can use the sample document provided below.
2. Access your US Mail OCR by clicking on the corresponding product card in the **Document Catalog**
3. From the left navigation, go to [**documentation**](https://docs.mindee.com/v1/platform-ui-tour/api-documentation#api-reference) **> API Reference**, you'll find sample code in popular languages and command line. {% tabs %} {% tab title="Python" %} ```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.us.UsMailV2, 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.us.UsMailV2, 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.Us.UsMail; 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(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::US::UsMail::UsMailV3 ) # 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" %} {% endtab %} {% tab title="undefined" %} ```java import com.mindee.MindeeClient; import com.mindee.input.LocalInputSource; import com.mindee.parsing.common.AsyncPredictResponse; import com.mindee.product.us.usmail.UsMailV2; 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 response = mindeeClient.enqueueAndParse( UsMailV2.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='us_mail' VERSION='2' 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 sourceFromPath("/path/to/the/file.ext"); // Parse the file asynchronously $apiResponse = $mindeeClient->enqueueAndParse(UsMailV2::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 your 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/us_mail/v2/documents/eb4c9ccc-a20c-46de-9f75-fd6fdc5115ec" }, "document": { "id": "eb4c9ccc-a20c-46de-9f75-fd6fdc5115ec", "inference": { "extras": {}, "finished_at": "2024-10-30T14:54:19.789000", "is_rotation_applied": true, "pages": [ { "extras": {}, "id": 0, "orientation": { "value": 0 }, "prediction": {} } ], "prediction": { "recipient_addresses": [ { "city": "Detroit", "complete": "1234 Market Street PMB 4321, Detroit, Michigan 12345", "is_address_change": false, "postal_code": "12345", "private_mailbox_number": "4321", "state": "MI", "street": "1234 Market Street" } ], "recipient_names": [ { "value": "Jane Doe" } ], "sender_address": { "city": "Dallas", "complete": "54321 Elm Street, Dallas, Texas 54321", "postal_code": "54321", "state": "TX", "street": "54321 Elm Street" }, "sender_name": { "value": "zed" } }, "processing_time": 3.072, "product": { "features": [ "sender_name", "sender_address", "recipient_names", "recipient_addresses" ], "name": "mindee/us_mail", "type": "standard", "version": "2.0" }, "started_at": "2024-10-30T14:54:16.506000" }, "n_pages": 1, "name": "US-mail-sample.jpg" }, "job": { "available_at": "2024-10-30T14:54:19.799000", "error": {}, "id": "02e29373-20fe-4a92-8245-7edc9d4ca8e5", "issued_at": "2024-10-30T14:54:16.506000", "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. * [Sender Name](#sender-name) * [Sender Address](#sender-address) * [Recipient Names](#recipient-names) * [Recipient Addresses](#recipient-addresses) ### Sender Name * **sender\_name**: The name of the sender. ```json { "sender_name": { "value": "zed" } } ``` ### Sender Address * **sender\_address**: The address of the sender. * **complete:** The complete address of the sender. * **street:** The street of the sender's address. * **city**: The city of the sender's address. * **state**: Second part of the ISO 3166-2 code, consisting of two letters indicating the US State. * **postal\_code**: The postal code of the sender's address. ```json { "sender_address": { "city": "Dallas", "complete": "54321 Elm Street, Dallas, Texas 54321", "postal_code": "54321", "state": "TX", "street": "54321 Elm Street" } } ``` ### Recipient Names * **recipient\_names**: The names of the recipients. ```json { "recipient_names": [ { "value": "Jane Doe" } ] } ``` ### Recipient Addresses * **recipient\_address**: The address of the recipients. * **complete:** The complete address of the recipient. * **street:** The street of the recipient’s address. * **city**: The city of the recipient’s address. * **state**: Second part of the ISO 3166-2 code, consisting of two letters indicating the US State. * **postal\_code**: The postal code of the recipient’s address. ```json { "recipient_addresses": [ { "city": "Detroit", "complete": "1234 Market Street PMB 4321, Detroit, Michigan 12345", "is_address_change": false, "postal_code": "12345", "private_mailbox_number": "4321", "state": "MI", "street": "1234 Market Street" } ] } ```