FormRecognizerClient Class
FormRecognizerClient extracts information from forms and images into structured data. It is the interface to use for analyzing with prebuilt models (receipts, business cards, invoices, identity documents), recognizing content/layout from forms, and analyzing custom forms from trained models. It provides different methods based on inputs from a URL and inputs from a stream.
Note
FormRecognizerClient should be used with API versions <=v2.1.
To use API versions 2022-08-31 and up, instantiate a DocumentAnalysisClient.
- Inheritance
-
azure.ai.formrecognizer._form_base_client.FormRecognizerClientBaseFormRecognizerClient
Constructor
FormRecognizerClient(endpoint: str, credential: AzureKeyCredential | TokenCredential, **kwargs: Any)Parameters
| Name | Description |
|---|---|
|
endpoint
Required
|
Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com). |
|
credential
Required
|
Credentials needed for the client to connect to Azure. This is an instance of AzureKeyCredential if using an API key or a token credential from identity. |
Keyword-Only Parameters
| Name | Description |
|---|---|
|
api_version
|
The API version of the service to use for requests. It defaults to API version v2.1. Setting to an older version may result in reduced feature compatibility. To use the latest supported API version and features, instantiate a DocumentAnalysisClient instead. |
Examples
Creating the FormRecognizerClient with an endpoint and API key.
from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import FormRecognizerClient
endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
form_recognizer_client = FormRecognizerClient(endpoint, AzureKeyCredential(key))
Creating the FormRecognizerClient with a token credential.
"""DefaultAzureCredential will use the values from these environment
variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET
"""
from azure.ai.formrecognizer import FormRecognizerClient
from azure.identity import DefaultAzureCredential
endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
credential = DefaultAzureCredential()
form_recognizer_client = FormRecognizerClient(endpoint, credential)
Methods
| begin_recognize_business_cards |
Extract field text and semantic values from a given business card. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'. See fields found on a business card here: https://aka.ms/formrecognizer/businesscardfields New in version v2.1: The begin_recognize_business_cards client method |
| begin_recognize_business_cards_from_url |
Extract field text and semantic values from a given business card. The input document must be the location (URL) of the card to be analyzed. See fields found on a business card here: https://aka.ms/formrecognizer/businesscardfields New in version v2.1: The begin_recognize_business_cards_from_url client method |
| begin_recognize_content |
Extract text and content/layout information from a given document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'. New in version v2.1: The pages, language and reading_order keyword arguments and support for image/bmp content |
| begin_recognize_content_from_url |
Extract text and layout information from a given document. The input document must be the location (URL) of the document to be analyzed. New in version v2.1: The pages, language and reading_order keyword arguments and support for image/bmp content |
| begin_recognize_custom_forms |
Analyze a custom form with a model trained with or without labels. The form to analyze should be of the same type as the forms that were used to train the model. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff', or 'image/bmp'. |
| begin_recognize_custom_forms_from_url |
Analyze a custom form with a model trained with or without labels. The form to analyze should be of the same type as the forms that were used to train the model. The input document must be the location (URL) of the document to be analyzed. |
| begin_recognize_identity_documents |
Extract field text and semantic values from a given identity document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'. See fields found on an identity document here: https://aka.ms/formrecognizer/iddocumentfields New in version v2.1: The begin_recognize_identity_documents client method |
| begin_recognize_identity_documents_from_url |
Extract field text and semantic values from a given identity document. The input document must be the location (URL) of the identity document to be analyzed. See fields found on an identity document here: https://aka.ms/formrecognizer/iddocumentfields New in version v2.1: The begin_recognize_identity_documents_from_url client method |
| begin_recognize_invoices |
Extract field text and semantic values from a given invoice. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'. See fields found on a invoice here: https://aka.ms/formrecognizer/invoicefields New in version v2.1: The begin_recognize_invoices client method |
| begin_recognize_invoices_from_url |
Extract field text and semantic values from a given invoice. The input document must be the location (URL) of the invoice to be analyzed. See fields found on a invoice card here: https://aka.ms/formrecognizer/invoicefields New in version v2.1: The begin_recognize_invoices_from_url client method |
| begin_recognize_receipts |
Extract field text and semantic values from a given sales receipt. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'. See fields found on a receipt here: https://aka.ms/formrecognizer/receiptfields New in version v2.1: The locale and pages keyword arguments and support for image/bmp content |
| begin_recognize_receipts_from_url |
Extract field text and semantic values from a given sales receipt. The input document must be the location (URL) of the receipt to be analyzed. See fields found on a receipt here: https://aka.ms/formrecognizer/receiptfields New in version v2.1: The locale and pages keyword arguments and support for image/bmp content |
| close |
Close the FormRecognizerClient session. |
| send_request |
Runs a network request using the client's existing pipeline. The request URL can be relative to the base URL. The service API version used for the request is the same as the client's unless otherwise specified. Overriding the client's configured API version in relative URL is supported on client with API version 2022-08-31 and later. Overriding in absolute URL supported on client with any API version. This method does not raise if the response is an error; to raise an exception, call raise_for_status() on the returned response object. For more information about how to send custom requests with this method, see https://aka.ms/azsdk/dpcodegen/python/send_request. |
begin_recognize_business_cards
Extract field text and semantic values from a given business card. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'.
See fields found on a business card here: https://aka.ms/formrecognizer/businesscardfields
New in version v2.1: The begin_recognize_business_cards client method
begin_recognize_business_cards(business_card: bytes | IO[bytes], **kwargs: Any) -> LROPoller[List[RecognizedForm]]Parameters
| Name | Description |
|---|---|
|
business_card
Required
|
JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes. |
Keyword-Only Parameters
| Name | Description |
|---|---|
|
locale
|
Locale of the business card. Supported locales include: en-US, en-AU, en-CA, en-GB, and en-IN. |
|
include_field_elements
|
Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field. |
|
pages
|
Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma. |
|
content_type
|
Content-type of the body sent to the API. Content-type is auto-detected, but can be overridden by passing this keyword argument. For options, see FormContentType. |
|
continuation_token
|
A continuation token to restart a poller from a saved state. |
Returns
| Type | Description |
|---|---|
|
An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm]. |
Exceptions
| Type | Description |
|---|---|
Examples
Recognize business cards from a file.
from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import FormRecognizerClient
endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
form_recognizer_client = FormRecognizerClient(
endpoint=endpoint, credential=AzureKeyCredential(key)
)
with open(path_to_sample_forms, "rb") as f:
poller = form_recognizer_client.begin_recognize_business_cards(business_card=f, locale="en-US")
business_cards = poller.result()
for idx, business_card in enumerate(business_cards):
print("--------Recognizing business card #{}--------".format(idx+1))
contact_names = business_card.fields.get("ContactNames")
if contact_names:
for contact_name in contact_names.value:
print("Contact First Name: {} has confidence: {}".format(
contact_name.value["FirstName"].value, contact_name.value["FirstName"].confidence
))
print("Contact Last Name: {} has confidence: {}".format(
contact_name.value["LastName"].value, contact_name.value["LastName"].confidence
))
company_names = business_card.fields.get("CompanyNames")
if company_names:
for company_name in company_names.value:
print("Company Name: {} has confidence: {}".format(company_name.value, company_name.confidence))
departments = business_card.fields.get("Departments")
if departments:
for department in departments.value:
print("Department: {} has confidence: {}".format(department.value, department.confidence))
job_titles = business_card.fields.get("JobTitles")
if job_titles:
for job_title in job_titles.value:
print("Job Title: {} has confidence: {}".format(job_title.value, job_title.confidence))
emails = business_card.fields.get("Emails")
if emails:
for email in emails.value:
print("Email: {} has confidence: {}".format(email.value, email.confidence))
websites = business_card.fields.get("Websites")
if websites:
for website in websites.value:
print("Website: {} has confidence: {}".format(website.value, website.confidence))
addresses = business_card.fields.get("Addresses")
if addresses:
for address in addresses.value:
print("Address: {} has confidence: {}".format(address.value, address.confidence))
mobile_phones = business_card.fields.get("MobilePhones")
if mobile_phones:
for phone in mobile_phones.value:
print("Mobile phone number: {} has confidence: {}".format(phone.value, phone.confidence))
faxes = business_card.fields.get("Faxes")
if faxes:
for fax in faxes.value:
print("Fax number: {} has confidence: {}".format(fax.value, fax.confidence))
work_phones = business_card.fields.get("WorkPhones")
if work_phones:
for work_phone in work_phones.value:
print("Work phone number: {} has confidence: {}".format(work_phone.value, work_phone.confidence))
other_phones = business_card.fields.get("OtherPhones")
if other_phones:
for other_phone in other_phones.value:
print("Other phone number: {} has confidence: {}".format(other_phone.value, other_phone.confidence))
begin_recognize_business_cards_from_url
Extract field text and semantic values from a given business card. The input document must be the location (URL) of the card to be analyzed.
See fields found on a business card here: https://aka.ms/formrecognizer/businesscardfields
New in version v2.1: The begin_recognize_business_cards_from_url client method
begin_recognize_business_cards_from_url(business_card_url: str, **kwargs: Any) -> LROPoller[List[RecognizedForm]]Parameters
| Name | Description |
|---|---|
|
business_card_url
Required
|
The URL of the business card to analyze. The input must be a valid, encoded URL of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP. |
Keyword-Only Parameters
| Name | Description |
|---|---|
|
locale
|
Locale of the business card. Supported locales include: en-US, en-AU, en-CA, en-GB, and en-IN. |
|
include_field_elements
|
Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field. |
|
pages
|
Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma. |
|
continuation_token
|
A continuation token to restart a poller from a saved state. |
Returns
| Type | Description |
|---|---|
|
An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm]. |
Exceptions
| Type | Description |
|---|---|
begin_recognize_content
Extract text and content/layout information from a given document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'.
New in version v2.1: The pages, language and reading_order keyword arguments and support for image/bmp content
begin_recognize_content(form: bytes | IO[bytes], **kwargs: Any) -> LROPoller[List[FormPage]]Parameters
| Name | Description |
|---|---|
|
form
Required
|
JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes. |
Keyword-Only Parameters
| Name | Description |
|---|---|
|
pages
|
Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma. |
|
language
|
The BCP-47 language code of the text in the document. See supported language codes here: https://docs.microsoft.com/azure/cognitive-services/form-recognizer/language-support. Content supports auto language identification and multilanguage documents, so only provide a language code if you would like to force the documented to be processed as that specific language. |
|
reading_order
|
Reading order algorithm to sort the text lines returned. Supported reading orders include: basic (default), natural. Set 'basic' to sort lines left to right and top to bottom, although in some cases proximity is treated with higher priority. Set 'natural' to sort lines by using positional information to keep nearby lines together. |
|
content_type
|
Content-type of the body sent to the API. Content-type is auto-detected, but can be overridden by passing this keyword argument. For options, see FormContentType. |
|
continuation_token
|
A continuation token to restart a poller from a saved state. |
Returns
| Type | Description |
|---|---|
|
An instance of an LROPoller. Call result() on the poller object to return a list[FormPage]. |
Exceptions
| Type | Description |
|---|---|
Examples
Recognize text and content/layout information from a form.
from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import FormRecognizerClient
endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
form_recognizer_client = FormRecognizerClient(endpoint=endpoint, credential=AzureKeyCredential(key))
with open(path_to_sample_forms, "rb") as f:
poller = form_recognizer_client.begin_recognize_content(form=f)
form_pages = poller.result()
for idx, content in enumerate(form_pages):
print("----Recognizing content from page #{}----".format(idx+1))
print("Page has width: {} and height: {}, measured with unit: {}".format(
content.width,
content.height,
content.unit
))
for table_idx, table in enumerate(content.tables):
print("Table # {} has {} rows and {} columns".format(table_idx, table.row_count, table.column_count))
print("Table # {} location on page: {}".format(table_idx, format_bounding_box(table.bounding_box)))
for cell in table.cells:
print("...Cell[{}][{}] has text '{}' within bounding box '{}'".format(
cell.row_index,
cell.column_index,
cell.text,
format_bounding_box(cell.bounding_box)
))
for line_idx, line in enumerate(content.lines):
print("Line # {} has word count '{}' and text '{}' within bounding box '{}'".format(
line_idx,
len(line.words),
line.text,
format_bounding_box(line.bounding_box)
))
if line.appearance:
if line.appearance.style_name == "handwriting" and line.appearance.style_confidence > 0.8:
print("Text line '{}' is handwritten and might be a signature.".format(line.text))
for word in line.words:
print("...Word '{}' has a confidence of {}".format(word.text, word.confidence))
for selection_mark in content.selection_marks:
print("Selection mark is '{}' within bounding box '{}' and has a confidence of {}".format(
selection_mark.state,
format_bounding_box(selection_mark.bounding_box),
selection_mark.confidence
))
print("----------------------------------------")
begin_recognize_content_from_url
Extract text and layout information from a given document. The input document must be the location (URL) of the document to be analyzed.
New in version v2.1: The pages, language and reading_order keyword arguments and support for image/bmp content
begin_recognize_content_from_url(form_url: str, **kwargs: Any) -> LROPoller[List[FormPage]]Parameters
| Name | Description |
|---|---|
|
form_url
Required
|
The URL of the form to analyze. The input must be a valid, encoded URL of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP. |
Keyword-Only Parameters
| Name | Description |
|---|---|
|
pages
|
Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma. |
|
language
|
The BCP-47 language code of the text in the document. See supported language codes here: https://docs.microsoft.com/azure/cognitive-services/form-recognizer/language-support. Content supports auto language identification and multilanguage documents, so only provide a language code if you would like to force the documented to be processed as that specific language. |
|
reading_order
|
Reading order algorithm to sort the text lines returned. Supported reading orders include: basic (default), natural. Set 'basic' to sort lines left to right and top to bottom, although in some cases proximity is treated with higher priority. Set 'natural' to sort lines by using positional information to keep nearby lines together. |
|
continuation_token
|
A continuation token to restart a poller from a saved state. |
Returns
| Type | Description |
|---|---|
|
An instance of an LROPoller. Call result() on the poller object to return a list[FormPage]. |
Exceptions
| Type | Description |
|---|---|
begin_recognize_custom_forms
Analyze a custom form with a model trained with or without labels. The form to analyze should be of the same type as the forms that were used to train the model. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff', or 'image/bmp'.
begin_recognize_custom_forms(model_id: str, form: bytes | IO[bytes], **kwargs: Any) -> LROPoller[List[RecognizedForm]]Parameters
| Name | Description |
|---|---|
|
model_id
Required
|
Custom model identifier. |
|
form
Required
|
JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes. |
Keyword-Only Parameters
| Name | Description |
|---|---|
|
include_field_elements
|
Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field. |
|
content_type
|
Content-type of the body sent to the API. Content-type is auto-detected, but can be overridden by passing this keyword argument. For options, see FormContentType. |
|
pages
|
Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma. |
|
continuation_token
|
A continuation token to restart a poller from a saved state. |
Returns
| Type | Description |
|---|---|
|
An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm]. |
Exceptions
| Type | Description |
|---|---|
Examples
Recognize fields and values from a custom form.
from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import FormRecognizerClient
endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
model_id = os.getenv("CUSTOM_TRAINED_MODEL_ID", custom_model_id)
form_recognizer_client = FormRecognizerClient(
endpoint=endpoint, credential=AzureKeyCredential(key)
)
# Make sure your form's type is included in the list of form types the custom model can recognize
with open(path_to_sample_forms, "rb") as f:
poller = form_recognizer_client.begin_recognize_custom_forms(
model_id=model_id, form=f, include_field_elements=True
)
forms = poller.result()
for idx, form in enumerate(forms):
print("--------Recognizing Form #{}--------".format(idx+1))
print("Form has type {}".format(form.form_type))
print("Form has form type confidence {}".format(form.form_type_confidence))
print("Form was analyzed with model with ID {}".format(form.model_id))
for name, field in form.fields.items():
# each field is of type FormField
# label_data is populated if you are using a model trained without labels,
# since the service needs to make predictions for labels if not explicitly given to it.
if field.label_data:
print("...Field '{}' has label '{}' with a confidence score of {}".format(
name,
field.label_data.text,
field.confidence
))
print("...Label '{}' has value '{}' with a confidence score of {}".format(
field.label_data.text if field.label_data else name, field.value, field.confidence
))
# iterate over tables, lines, and selection marks on each page
for page in form.pages:
for i, table in enumerate(page.tables):
print("\nTable {} on page {}".format(i+1, table.page_number))
for cell in table.cells:
print("...Cell[{}][{}] has text '{}' with confidence {}".format(
cell.row_index, cell.column_index, cell.text, cell.confidence
))
print("\nLines found on page {}".format(page.page_number))
for line in page.lines:
print("...Line '{}' is made up of the following words: ".format(line.text))
for word in line.words:
print("......Word '{}' has a confidence of {}".format(
word.text,
word.confidence
))
if page.selection_marks:
print("\nSelection marks found on page {}".format(page.page_number))
for selection_mark in page.selection_marks:
print("......Selection mark is '{}' and has a confidence of {}".format(
selection_mark.state,
selection_mark.confidence
))
print("-----------------------------------")
begin_recognize_custom_forms_from_url
Analyze a custom form with a model trained with or without labels. The form to analyze should be of the same type as the forms that were used to train the model. The input document must be the location (URL) of the document to be analyzed.
begin_recognize_custom_forms_from_url(model_id: str, form_url: str, **kwargs: Any) -> LROPoller[List[RecognizedForm]]Parameters
| Name | Description |
|---|---|
|
model_id
Required
|
Custom model identifier. |
|
form_url
Required
|
The URL of the form to analyze. The input must be a valid, encoded URL of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP. |
Keyword-Only Parameters
| Name | Description |
|---|---|
|
include_field_elements
|
Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field. |
|
pages
|
Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma. |
|
continuation_token
|
A continuation token to restart a poller from a saved state. |
Returns
| Type | Description |
|---|---|
|
An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm]. |
Exceptions
| Type | Description |
|---|---|
begin_recognize_identity_documents
Extract field text and semantic values from a given identity document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'.
See fields found on an identity document here: https://aka.ms/formrecognizer/iddocumentfields
New in version v2.1: The begin_recognize_identity_documents client method
begin_recognize_identity_documents(identity_document: bytes | IO[bytes], **kwargs: Any) -> LROPoller[List[RecognizedForm]]Parameters
| Name | Description |
|---|---|
|
identity_document
Required
|
JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes. |
Keyword-Only Parameters
| Name | Description |
|---|---|
|
include_field_elements
|
Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field. |
|
content_type
|
Content-type of the body sent to the API. Content-type is auto-detected, but can be overridden by passing this keyword argument. For options, see FormContentType. |
|
continuation_token
|
A continuation token to restart a poller from a saved state. |
|
pages
|
Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma. |
Returns
| Type | Description |
|---|---|
|
An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm]. |
Exceptions
| Type | Description |
|---|---|
Examples
Recognize identity document fields.
from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import FormRecognizerClient
endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
form_recognizer_client = FormRecognizerClient(
endpoint=endpoint, credential=AzureKeyCredential(key)
)
with open(path_to_sample_forms, "rb") as f:
poller = form_recognizer_client.begin_recognize_identity_documents(identity_document=f)
id_documents = poller.result()
for idx, id_document in enumerate(id_documents):
print("--------Recognizing ID document #{}--------".format(idx+1))
first_name = id_document.fields.get("FirstName")
if first_name:
print("First Name: {} has confidence: {}".format(first_name.value, first_name.confidence))
last_name = id_document.fields.get("LastName")
if last_name:
print("Last Name: {} has confidence: {}".format(last_name.value, last_name.confidence))
document_number = id_document.fields.get("DocumentNumber")
if document_number:
print("Document Number: {} has confidence: {}".format(document_number.value, document_number.confidence))
dob = id_document.fields.get("DateOfBirth")
if dob:
print("Date of Birth: {} has confidence: {}".format(dob.value, dob.confidence))
doe = id_document.fields.get("DateOfExpiration")
if doe:
print("Date of Expiration: {} has confidence: {}".format(doe.value, doe.confidence))
sex = id_document.fields.get("Sex")
if sex:
print("Sex: {} has confidence: {}".format(sex.value, sex.confidence))
address = id_document.fields.get("Address")
if address:
print("Address: {} has confidence: {}".format(address.value, address.confidence))
country_region = id_document.fields.get("CountryRegion")
if country_region:
print("Country/Region: {} has confidence: {}".format(country_region.value, country_region.confidence))
region = id_document.fields.get("Region")
if region:
print("Region: {} has confidence: {}".format(region.value, region.confidence))
begin_recognize_identity_documents_from_url
Extract field text and semantic values from a given identity document. The input document must be the location (URL) of the identity document to be analyzed.
See fields found on an identity document here: https://aka.ms/formrecognizer/iddocumentfields
New in version v2.1: The begin_recognize_identity_documents_from_url client method
begin_recognize_identity_documents_from_url(identity_document_url: str, **kwargs: Any) -> LROPoller[List[RecognizedForm]]Parameters
| Name | Description |
|---|---|
|
identity_document_url
Required
|
The URL of the identity document to analyze. The input must be a valid, encoded URL of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP. |
Keyword-Only Parameters
| Name | Description |
|---|---|
|
include_field_elements
|
Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field. |
|
continuation_token
|
A continuation token to restart a poller from a saved state. |
|
pages
|
Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma. |
Returns
| Type | Description |
|---|---|
|
An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm]. |
Exceptions
| Type | Description |
|---|---|
begin_recognize_invoices
Extract field text and semantic values from a given invoice. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'.
See fields found on a invoice here: https://aka.ms/formrecognizer/invoicefields
New in version v2.1: The begin_recognize_invoices client method
begin_recognize_invoices(invoice: bytes | IO[bytes], **kwargs: Any) -> LROPoller[List[RecognizedForm]]Parameters
| Name | Description |
|---|---|
|
invoice
Required
|
JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes. |
Keyword-Only Parameters
| Name | Description |
|---|---|
|
locale
|
Locale of the invoice. Supported locales include: en-US |
|
include_field_elements
|
Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field. |
|
pages
|
Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma. |
|
content_type
|
Content-type of the body sent to the API. Content-type is auto-detected, but can be overridden by passing this keyword argument. For options, see FormContentType. |
|
continuation_token
|
A continuation token to restart a poller from a saved state. |
Returns
| Type | Description |
|---|---|
|
An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm]. |
Exceptions
| Type | Description |
|---|---|
Examples
Recognize invoices from a file.
from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import FormRecognizerClient
endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
form_recognizer_client = FormRecognizerClient(
endpoint=endpoint, credential=AzureKeyCredential(key)
)
with open(path_to_sample_forms, "rb") as f:
poller = form_recognizer_client.begin_recognize_invoices(invoice=f, locale="en-US")
invoices = poller.result()
for idx, invoice in enumerate(invoices):
print("--------Recognizing invoice #{}--------".format(idx+1))
vendor_name = invoice.fields.get("VendorName")
if vendor_name:
print("Vendor Name: {} has confidence: {}".format(vendor_name.value, vendor_name.confidence))
vendor_address = invoice.fields.get("VendorAddress")
if vendor_address:
print("Vendor Address: {} has confidence: {}".format(vendor_address.value, vendor_address.confidence))
vendor_address_recipient = invoice.fields.get("VendorAddressRecipient")
if vendor_address_recipient:
print("Vendor Address Recipient: {} has confidence: {}".format(vendor_address_recipient.value, vendor_address_recipient.confidence))
customer_name = invoice.fields.get("CustomerName")
if customer_name:
print("Customer Name: {} has confidence: {}".format(customer_name.value, customer_name.confidence))
customer_id = invoice.fields.get("CustomerId")
if customer_id:
print("Customer Id: {} has confidence: {}".format(customer_id.value, customer_id.confidence))
customer_address = invoice.fields.get("CustomerAddress")
if customer_address:
print("Customer Address: {} has confidence: {}".format(customer_address.value, customer_address.confidence))
customer_address_recipient = invoice.fields.get("CustomerAddressRecipient")
if customer_address_recipient:
print("Customer Address Recipient: {} has confidence: {}".format(customer_address_recipient.value, customer_address_recipient.confidence))
invoice_id = invoice.fields.get("InvoiceId")
if invoice_id:
print("Invoice Id: {} has confidence: {}".format(invoice_id.value, invoice_id.confidence))
invoice_date = invoice.fields.get("InvoiceDate")
if invoice_date:
print("Invoice Date: {} has confidence: {}".format(invoice_date.value, invoice_date.confidence))
invoice_total = invoice.fields.get("InvoiceTotal")
if invoice_total:
print("Invoice Total: {} has confidence: {}".format(invoice_total.value, invoice_total.confidence))
due_date = invoice.fields.get("DueDate")
if due_date:
print("Due Date: {} has confidence: {}".format(due_date.value, due_date.confidence))
purchase_order = invoice.fields.get("PurchaseOrder")
if purchase_order:
print("Purchase Order: {} has confidence: {}".format(purchase_order.value, purchase_order.confidence))
billing_address = invoice.fields.get("BillingAddress")
if billing_address:
print("Billing Address: {} has confidence: {}".format(billing_address.value, billing_address.confidence))
billing_address_recipient = invoice.fields.get("BillingAddressRecipient")
if billing_address_recipient:
print("Billing Address Recipient: {} has confidence: {}".format(billing_address_recipient.value, billing_address_recipient.confidence))
shipping_address = invoice.fields.get("ShippingAddress")
if shipping_address:
print("Shipping Address: {} has confidence: {}".format(shipping_address.value, shipping_address.confidence))
shipping_address_recipient = invoice.fields.get("ShippingAddressRecipient")
if shipping_address_recipient:
print("Shipping Address Recipient: {} has confidence: {}".format(shipping_address_recipient.value, shipping_address_recipient.confidence))
print("Invoice items:")
for idx, item in enumerate(invoice.fields.get("Items").value):
print("...Item #{}".format(idx+1))
item_description = item.value.get("Description")
if item_description:
print("......Description: {} has confidence: {}".format(item_description.value, item_description.confidence))
item_quantity = item.value.get("Quantity")
if item_quantity:
print("......Quantity: {} has confidence: {}".format(item_quantity.value, item_quantity.confidence))
unit = item.value.get("Unit")
if unit:
print("......Unit: {} has confidence: {}".format(unit.value, unit.confidence))
unit_price = item.value.get("UnitPrice")
if unit_price:
print("......Unit Price: {} has confidence: {}".format(unit_price.value, unit_price.confidence))
product_code = item.value.get("ProductCode")
if product_code:
print("......Product Code: {} has confidence: {}".format(product_code.value, product_code.confidence))
item_date = item.value.get("Date")
if item_date:
print("......Date: {} has confidence: {}".format(item_date.value, item_date.confidence))
tax = item.value.get("Tax")
if tax:
print("......Tax: {} has confidence: {}".format(tax.value, tax.confidence))
amount = item.value.get("Amount")
if amount:
print("......Amount: {} has confidence: {}".format(amount.value, amount.confidence))
subtotal = invoice.fields.get("SubTotal")
if subtotal:
print("Subtotal: {} has confidence: {}".format(subtotal.value, subtotal.confidence))
total_tax = invoice.fields.get("TotalTax")
if total_tax:
print("Total Tax: {} has confidence: {}".format(total_tax.value, total_tax.confidence))
previous_unpaid_balance = invoice.fields.get("PreviousUnpaidBalance")
if previous_unpaid_balance:
print("Previous Unpaid Balance: {} has confidence: {}".format(previous_unpaid_balance.value, previous_unpaid_balance.confidence))
amount_due = invoice.fields.get("AmountDue")
if amount_due:
print("Amount Due: {} has confidence: {}".format(amount_due.value, amount_due.confidence))
service_start_date = invoice.fields.get("ServiceStartDate")
if service_start_date:
print("Service Start Date: {} has confidence: {}".format(service_start_date.value, service_start_date.confidence))
service_end_date = invoice.fields.get("ServiceEndDate")
if service_end_date:
print("Service End Date: {} has confidence: {}".format(service_end_date.value, service_end_date.confidence))
service_address = invoice.fields.get("ServiceAddress")
if service_address:
print("Service Address: {} has confidence: {}".format(service_address.value, service_address.confidence))
service_address_recipient = invoice.fields.get("ServiceAddressRecipient")
if service_address_recipient:
print("Service Address Recipient: {} has confidence: {}".format(service_address_recipient.value, service_address_recipient.confidence))
remittance_address = invoice.fields.get("RemittanceAddress")
if remittance_address:
print("Remittance Address: {} has confidence: {}".format(remittance_address.value, remittance_address.confidence))
remittance_address_recipient = invoice.fields.get("RemittanceAddressRecipient")
if remittance_address_recipient:
print("Remittance Address Recipient: {} has confidence: {}".format(remittance_address_recipient.value, remittance_address_recipient.confidence))
begin_recognize_invoices_from_url
Extract field text and semantic values from a given invoice. The input document must be the location (URL) of the invoice to be analyzed.
See fields found on a invoice card here: https://aka.ms/formrecognizer/invoicefields
New in version v2.1: The begin_recognize_invoices_from_url client method
begin_recognize_invoices_from_url(invoice_url: str, **kwargs: Any) -> LROPoller[List[RecognizedForm]]Parameters
| Name | Description |
|---|---|
|
invoice_url
Required
|
The URL of the invoice to analyze. The input must be a valid, encoded URL of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP. |
Keyword-Only Parameters
| Name | Description |
|---|---|
|
locale
|
Locale of the invoice. Supported locales include: en-US |
|
include_field_elements
|
Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field. |
|
pages
|
Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma. |
|
continuation_token
|
A continuation token to restart a poller from a saved state. |
Returns
| Type | Description |
|---|---|
|
An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm]. |
Exceptions
| Type | Description |
|---|---|
begin_recognize_receipts
Extract field text and semantic values from a given sales receipt. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'.
See fields found on a receipt here: https://aka.ms/formrecognizer/receiptfields
New in version v2.1: The locale and pages keyword arguments and support for image/bmp content
begin_recognize_receipts(receipt: bytes | IO[bytes], **kwargs: Any) -> LROPoller[List[RecognizedForm]]Parameters
| Name | Description |
|---|---|
|
receipt
Required
|
JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes. |
Keyword-Only Parameters
| Name | Description |
|---|---|
|
include_field_elements
|
Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field. |
|
content_type
|
Content-type of the body sent to the API. Content-type is auto-detected, but can be overridden by passing this keyword argument. For options, see FormContentType. |
|
continuation_token
|
A continuation token to restart a poller from a saved state. |
|
locale
|
Locale of the receipt. Supported locales include: en-US, en-AU, en-CA, en-GB, and en-IN. |
|
pages
|
Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma. |
Returns
| Type | Description |
|---|---|
|
An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm]. |
Exceptions
| Type | Description |
|---|---|
Examples
Recognize sales receipt fields.
from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import FormRecognizerClient
endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
form_recognizer_client = FormRecognizerClient(
endpoint=endpoint, credential=AzureKeyCredential(key)
)
with open(path_to_sample_forms, "rb") as f:
poller = form_recognizer_client.begin_recognize_receipts(receipt=f, locale="en-US")
receipts = poller.result()
for idx, receipt in enumerate(receipts):
print("--------Recognizing receipt #{}--------".format(idx+1))
receipt_type = receipt.fields.get("ReceiptType")
if receipt_type:
print("Receipt Type: {} has confidence: {}".format(receipt_type.value, receipt_type.confidence))
merchant_name = receipt.fields.get("MerchantName")
if merchant_name:
print("Merchant Name: {} has confidence: {}".format(merchant_name.value, merchant_name.confidence))
transaction_date = receipt.fields.get("TransactionDate")
if transaction_date:
print("Transaction Date: {} has confidence: {}".format(transaction_date.value, transaction_date.confidence))
if receipt.fields.get("Items"):
print("Receipt items:")
for idx, item in enumerate(receipt.fields.get("Items").value):
print("...Item #{}".format(idx+1))
item_name = item.value.get("Name")
if item_name:
print("......Item Name: {} has confidence: {}".format(item_name.value, item_name.confidence))
item_quantity = item.value.get("Quantity")
if item_quantity:
print("......Item Quantity: {} has confidence: {}".format(item_quantity.value, item_quantity.confidence))
item_price = item.value.get("Price")
if item_price:
print("......Individual Item Price: {} has confidence: {}".format(item_price.value, item_price.confidence))
item_total_price = item.value.get("TotalPrice")
if item_total_price:
print("......Total Item Price: {} has confidence: {}".format(item_total_price.value, item_total_price.confidence))
subtotal = receipt.fields.get("Subtotal")
if subtotal:
print("Subtotal: {} has confidence: {}".format(subtotal.value, subtotal.confidence))
tax = receipt.fields.get("Tax")
if tax:
print("Tax: {} has confidence: {}".format(tax.value, tax.confidence))
tip = receipt.fields.get("Tip")
if tip:
print("Tip: {} has confidence: {}".format(tip.value, tip.confidence))
total = receipt.fields.get("Total")
if total:
print("Total: {} has confidence: {}".format(total.value, total.confidence))
print("--------------------------------------")
begin_recognize_receipts_from_url
Extract field text and semantic values from a given sales receipt. The input document must be the location (URL) of the receipt to be analyzed.
See fields found on a receipt here: https://aka.ms/formrecognizer/receiptfields
New in version v2.1: The locale and pages keyword arguments and support for image/bmp content
begin_recognize_receipts_from_url(receipt_url: str, **kwargs: Any) -> LROPoller[List[RecognizedForm]]Parameters
| Name | Description |
|---|---|
|
receipt_url
Required
|
The URL of the receipt to analyze. The input must be a valid, encoded URL of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP. |
Keyword-Only Parameters
| Name | Description |
|---|---|
|
include_field_elements
|
Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field. |
|
continuation_token
|
A continuation token to restart a poller from a saved state. |
|
locale
|
Locale of the receipt. Supported locales include: en-US, en-AU, en-CA, en-GB, and en-IN. |
|
pages
|
Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma. |
Returns
| Type | Description |
|---|---|
|
An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm]. |
Exceptions
| Type | Description |
|---|---|
Examples
Recognize sales receipt fields from a URL.
from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import FormRecognizerClient
endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
form_recognizer_client = FormRecognizerClient(
endpoint=endpoint, credential=AzureKeyCredential(key)
)
url = "https://raw.githubusercontent.com/Azure/azure-sdk-for-python/main/sdk/formrecognizer/azure-ai-formrecognizer/tests/sample_forms/receipt/contoso-receipt.png"
poller = form_recognizer_client.begin_recognize_receipts_from_url(receipt_url=url)
receipts = poller.result()
for idx, receipt in enumerate(receipts):
print("--------Recognizing receipt #{}--------".format(idx+1))
receipt_type = receipt.fields.get("ReceiptType")
if receipt_type:
print("Receipt Type: {} has confidence: {}".format(receipt_type.value, receipt_type.confidence))
merchant_name = receipt.fields.get("MerchantName")
if merchant_name:
print("Merchant Name: {} has confidence: {}".format(merchant_name.value, merchant_name.confidence))
transaction_date = receipt.fields.get("TransactionDate")
if transaction_date:
print("Transaction Date: {} has confidence: {}".format(transaction_date.value, transaction_date.confidence))
if receipt.fields.get("Items"):
print("Receipt items:")
for idx, item in enumerate(receipt.fields.get("Items").value):
print("...Item #{}".format(idx+1))
item_name = item.value.get("Name")
if item_name:
print("......Item Name: {} has confidence: {}".format(item_name.value, item_name.confidence))
item_quantity = item.value.get("Quantity")
if item_quantity:
print("......Item Quantity: {} has confidence: {}".format(item_quantity.value, item_quantity.confidence))
item_price = item.value.get("Price")
if item_price:
print("......Individual Item Price: {} has confidence: {}".format(item_price.value, item_price.confidence))
item_total_price = item.value.get("TotalPrice")
if item_total_price:
print("......Total Item Price: {} has confidence: {}".format(item_total_price.value, item_total_price.confidence))
subtotal = receipt.fields.get("Subtotal")
if subtotal:
print("Subtotal: {} has confidence: {}".format(subtotal.value, subtotal.confidence))
tax = receipt.fields.get("Tax")
if tax:
print("Tax: {} has confidence: {}".format(tax.value, tax.confidence))
tip = receipt.fields.get("Tip")
if tip:
print("Tip: {} has confidence: {}".format(tip.value, tip.confidence))
total = receipt.fields.get("Total")
if total:
print("Total: {} has confidence: {}".format(total.value, total.confidence))
print("--------------------------------------")
close
Close the FormRecognizerClient session.
close() -> NoneKeyword-Only Parameters
| Name | Description |
|---|---|
|
locale
|
Locale of the business card. Supported locales include: en-US, en-AU, en-CA, en-GB, and en-IN. |
|
include_field_elements
|
Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field. |
|
pages
|
Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma. |
|
content_type
|
Content-type of the body sent to the API. Content-type is auto-detected, but can be overridden by passing this keyword argument. For options, see FormContentType. |
|
continuation_token
|
A continuation token to restart a poller from a saved state. |
Exceptions
| Type | Description |
|---|---|
send_request
Runs a network request using the client's existing pipeline.
The request URL can be relative to the base URL. The service API version used for the request is the same as the client's unless otherwise specified. Overriding the client's configured API version in relative URL is supported on client with API version 2022-08-31 and later. Overriding in absolute URL supported on client with any API version. This method does not raise if the response is an error; to raise an exception, call raise_for_status() on the returned response object. For more information about how to send custom requests with this method, see https://aka.ms/azsdk/dpcodegen/python/send_request.
send_request(request: HttpRequest, *, stream: bool = False, **kwargs) -> HttpResponseParameters
| Name | Description |
|---|---|
|
request
Required
|
The network request you want to make. |
Keyword-Only Parameters
| Name | Description |
|---|---|
|
stream
|
Whether the response payload will be streamed. Defaults to False. |
Returns
| Type | Description |
|---|---|
|
The response of your network call. Does not do error handling on your response. |
Exceptions
| Type | Description |
|---|---|
Azure SDK for Python
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for