|
| 1 | + |
| 2 | +# Quickstart: Extract business card data using the Form Recognizer REST API with Python |
| 3 | + |
| 4 | +In this quickstart, you'll use the Azure Form Recognizer REST API with Python to extract and identify relevant information on business cards. |
| 5 | + |
| 6 | +If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin. |
| 7 | + |
| 8 | +## Prerequisites |
| 9 | + |
| 10 | +To complete this quickstart, you must have: |
| 11 | +- [Python](https://www.python.org/downloads/) installed (if you want to run the sample locally). |
| 12 | +- An image of a business card. You can use a [sample image](https://raw.githubusercontent.com/Azure-Samples/cognitive-services-REST-api-samples/master/curl/form-recognizer/business-card-english.jpg) for this quickstart. |
| 13 | + |
| 14 | +> [!NOTE] |
| 15 | +> This quickstart uses a local file. To use a remote business card image accessed by URL instead, see the [reference documentation](https://westus2.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1-preview-2/operations/AnalyzeBusinessCardAsync). |
| 16 | +
|
| 17 | +## Create a Form Recognizer resource |
| 18 | + |
| 19 | +Go to the Azure portal and <a href="https://ms.portal.azure.com/#create/Microsoft.CognitiveServicesFormRecognizer" title="Create a new Form Recognizer resource" target="_blank">create a new Form Recognizer resource <span class="docon docon-navigate-external x-hidden-focus"></span></a>. In the **Create** pane, provide the following information: |
| 20 | + |
| 21 | +| | | |
| 22 | +|--|--| |
| 23 | +| **Name** | A descriptive name for your resource. We recommend using a descriptive name, for example *MyNameFormRecognizer*. | |
| 24 | +| **Subscription** | Select the Azure subscription which has been granted access. | |
| 25 | +| **Location** | The location of your cognitive service instance. Different locations may introduce latency, but have no impact on the runtime availability of your resource. | |
| 26 | +| **Pricing tier** | The cost of your resource depends on the pricing tier you choose and your usage. For more information, see the API [pricing details](https://azure.microsoft.com/pricing/details/cognitive-services/). |
| 27 | +| **Resource group** | The Azure resource group that will contain your resource. You can create a new group or add it to a pre-existing group. | |
| 28 | + |
| 29 | +> [!NOTE] |
| 30 | +> Normally when you create a Cognitive Service resource in the Azure portal, you have the option to create a multi-service subscription key (used across multiple cognitive services) or a single-service subscription key (used only with a specific cognitive service). However currently Form Recognizer is not included in the multi-service subscription. |
| 31 | +
|
| 32 | +When your Form Recognizer resource finishes deploying, find and select it from the **All resources** list in the portal. Your key and endpoint will be located on the resource's key and endpoint page, under resource management. Save both of these to a temporary location before going forward. |
| 33 | + |
| 34 | +## Analyze a business card |
| 35 | + |
| 36 | +To start analyzing a business card, you call the **[Analyze Business Card](https://westus2.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1-preview-2/operations/AnalyzeBusinessCardAsync)** API using the Python script below. Before you run the script, make these changes: |
| 37 | + |
| 38 | +1. Replace `<endpoint>` with the endpoint that you obtained with your Form Recognizer subscription. |
| 39 | +1. Replace `<path to your business card>` with the local path to your business card image or PDF. |
| 40 | +1. Replace `<subscription key>` with the subscription key you copied from the previous step. |
| 41 | +1. Replace `<file type>` with 'image/jpeg', 'image/png', 'application/pdf', or 'image/tiff'. |
| 42 | + |
| 43 | + ```python |
| 44 | + ########### Python Form Recognizer Async Business Cards ############# |
| 45 | + |
| 46 | + import json |
| 47 | + import time |
| 48 | + from requests import get, post |
| 49 | + |
| 50 | + # Endpoint URL |
| 51 | + endpoint = r"<endpoint>" |
| 52 | + apim_key = "<subscription key>" |
| 53 | + post_url = endpoint + "/formrecognizer/v2.1-preview.2/prebuilt/businessCard/analyze" |
| 54 | + source = r"<path to your business card>" |
| 55 | + content_type = "<file type>" |
| 56 | + |
| 57 | + headers = { |
| 58 | + # Request headers |
| 59 | + 'Content-Type': content_type, |
| 60 | + 'Ocp-Apim-Subscription-Key': apim_key, |
| 61 | + } |
| 62 | + |
| 63 | + params = { |
| 64 | + "includeTextDetails": True # True to output all recognized text |
| 65 | + } |
| 66 | + |
| 67 | + with open(source, "rb") as f: |
| 68 | + data_bytes = f.read() |
| 69 | + |
| 70 | + try: |
| 71 | + resp = post(url = post_url, data = data_bytes, headers = headers, params = params) |
| 72 | + if resp.status_code != 202: |
| 73 | + print("POST analyze failed:\n%s" % resp.text) |
| 74 | + quit() |
| 75 | + print("POST analyze succeeded:\n%s" % resp.headers) |
| 76 | + get_url = resp.headers["operation-location"] |
| 77 | + except Exception as e: |
| 78 | + print("POST analyze failed:\n%s" % str(e)) |
| 79 | + quit() |
| 80 | + ``` |
| 81 | + |
| 82 | +1. Save the code in a file with a .py extension. For example, *form-recognizer-businesscards.py*. |
| 83 | +1. Open a command prompt window. |
| 84 | +1. At the prompt, use the `python` command to run the sample. For example, `python form-recognizer-businesscards.py`. |
| 85 | + |
| 86 | +You'll receive a `202 (Success)` response that includes an **Operation-Location** header, which the script will print to the console. This header contains a result ID that you can use to query the status of the long running operation and get the results. In the following example value, the string after `operations/` is the result ID. |
| 87 | + |
| 88 | +```console |
| 89 | +https://cognitiveservice/formrecognizer/v2.1-preview.2/prebuilt/businessCard/analyzeResults/54f0b076-4e38-43e5-81bd-b85b8835fdfb |
| 90 | +``` |
| 91 | + |
| 92 | +## Get the business card results |
| 93 | + |
| 94 | +After you've called the **Analyze Business Card** API, you call the **[Get Analyze Business Card Result](https://westcentralus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1-preview-2/operations/GetAnalyzeBusinessCardResult)** API to get the status of the operation and the extracted data. Add the following code to the bottom of your Python script. This uses the result ID value in a new API call. This script calls the API at regular intervals until the results are available. We recommend an interval of one second or more. |
| 95 | + |
| 96 | +```python |
| 97 | +n_tries = 10 |
| 98 | +n_try = 0 |
| 99 | +wait_sec = 6 |
| 100 | +while n_try < n_tries: |
| 101 | + try: |
| 102 | + resp = get(url = get_url, headers = {"Ocp-Apim-Subscription-Key": apim_key}) |
| 103 | + resp_json = json.loads(resp.text) |
| 104 | + if resp.status_code != 200: |
| 105 | + print("GET Business card results failed:\n%s" % resp_json) |
| 106 | + quit() |
| 107 | + status = resp_json["status"] |
| 108 | + if status == "succeeded": |
| 109 | + print("Business card Analysis succeeded:\n%s" % resp_json) |
| 110 | + quit() |
| 111 | + if status == "failed": |
| 112 | + print("Analysis failed:\n%s" % resp_json) |
| 113 | + quit() |
| 114 | + # Analysis still running. Wait and retry. |
| 115 | + time.sleep(wait_sec) |
| 116 | + n_try += 1 |
| 117 | + except Exception as e: |
| 118 | + msg = "GET analyze results failed:\n%s" % str(e) |
| 119 | + print(msg) |
| 120 | + quit() |
| 121 | +``` |
| 122 | + |
| 123 | +1. Save the script. |
| 124 | +1. Again use the `python` command to run the sample. For example, `python form-recognizer-businesscards.py`. |
| 125 | + |
| 126 | +### Examine the response |
| 127 | + |
| 128 | +This sample illustrates the JSON output returned by Form Recognizer. It has been truncated for readability. |
| 129 | + |
| 130 | +```json |
| 131 | +{ |
| 132 | + "status": "succeeded", |
| 133 | + "createdDateTime": "2020-06-04T08:19:29Z", |
| 134 | + "lastUpdatedDateTime": "2020-06-04T08:19:35Z", |
| 135 | + "analyzeResult": { |
| 136 | + "version": "2.1.1", |
| 137 | + "readResults": [ |
| 138 | + { |
| 139 | + "page": 1, |
| 140 | + "angle": -17.0956, |
| 141 | + "width": 4032, |
| 142 | + "height": 3024, |
| 143 | + "unit": "pixel" |
| 144 | + } |
| 145 | + ], |
| 146 | + "documentResults": [ |
| 147 | + { |
| 148 | + "docType": "prebuilt:businesscard", |
| 149 | + "pageRange": [ |
| 150 | + 1, |
| 151 | + 1 |
| 152 | + ], |
| 153 | + "fields": { |
| 154 | + "ContactNames": { |
| 155 | + "type": "array", |
| 156 | + "valueArray": [ |
| 157 | + { |
| 158 | + "type": "object", |
| 159 | + "valueObject": { |
| 160 | + "FirstName": { |
| 161 | + "type": "string", |
| 162 | + "valueString": "Avery", |
| 163 | + "text": "Avery", |
| 164 | + "boundingBox": [ |
| 165 | + 703, |
| 166 | + 1096, |
| 167 | + 1134, |
| 168 | + 989, |
| 169 | + 1165, |
| 170 | + 1109, |
| 171 | + 733, |
| 172 | + 1206 |
| 173 | + ], |
| 174 | + "page": 1 |
| 175 | + }, |
| 176 | + "text": "Dr. Avery Smith", |
| 177 | + "boundingBox": [ |
| 178 | + 419.3, |
| 179 | + 1154.6, |
| 180 | + 1589.6, |
| 181 | + 877.9, |
| 182 | + 1618.9, |
| 183 | + 1001.7, |
| 184 | + 448.6, |
| 185 | + 1278.4 |
| 186 | + ], |
| 187 | + "confidence": 0.993 |
| 188 | + } |
| 189 | + ] |
| 190 | + }, |
| 191 | + "Emails": { |
| 192 | + "type": "array", |
| 193 | + "valueArray": [ |
| 194 | + { |
| 195 | + "type": "string", |
| 196 | + "valueString": "avery.smith@contoso.com", |
| 197 | + "text": "avery.smith@contoso.com", |
| 198 | + "boundingBox": [ |
| 199 | + 2107, |
| 200 | + 934, |
| 201 | + 2917, |
| 202 | + 696, |
| 203 | + 2935, |
| 204 | + 764, |
| 205 | + 2126, |
| 206 | + 995 |
| 207 | + ], |
| 208 | + "page": 1, |
| 209 | + "confidence": 0.99 |
| 210 | + } |
| 211 | + ] |
| 212 | + }, |
| 213 | + "Websites": { |
| 214 | + "type": "array", |
| 215 | + "valueArray": [ |
| 216 | + { |
| 217 | + "type": "string", |
| 218 | + "valueString": "https://www.contoso.com/", |
| 219 | + "text": "https://www.contoso.com/", |
| 220 | + "boundingBox": [ |
| 221 | + 2121, |
| 222 | + 1002, |
| 223 | + 2992, |
| 224 | + 755, |
| 225 | + 3014, |
| 226 | + 826, |
| 227 | + 2143, |
| 228 | + 1077 |
| 229 | + ], |
| 230 | + "page": 1, |
| 231 | + "confidence": 0.995 |
| 232 | + } |
| 233 | + ] |
| 234 | + } |
| 235 | + } |
| 236 | + } |
| 237 | + ] |
| 238 | + } |
| 239 | +} |
| 240 | +``` |
| 241 | + |
| 242 | +The script will print responses to the console until the **Analyze Business Card** operation completes. |
| 243 | +The `"readResults"` node contains all of the recognized text. Text is organized by page, then by line, then by individual words. The `"documentResults"` node contains the business-card-specific values that the model discovered. This is where you'll find useful contact information like the company name, first name, last name, phone number, and so on. |
| 244 | + |
| 245 | + |
| 246 | +## Next steps |
| 247 | + |
| 248 | +In this quickstart, you used the Form Recognizer REST API with Python to extract the content of a business card. Next, see the reference documentation to explore the Form Recognizer API in more depth. |
| 249 | + |
| 250 | +* [REST API reference documentation](https://westcentralus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1-preview-2/operations/AnalyzeBusinessCardAsync) |
0 commit comments