Detecting Text

The OCR API allows you to extract text from images in virtually any language, including digits, special characters, single and multiline texts. This endpoint is separate from the search API, providing flexibility in how you use the extracted text.

API Endpoint

POST https://api.partium.io/1/find/ocr/detect

Request Format

The API accepts images in many common formats, including but not limited to:

• PNG
• JPEG/JPG
• BMP
• TIFF
• GIF
• WebP
• PPM
• PGM

You can send the image either as:

1. Raw binary data with Content-Type: image/png (or other image type)
2. Multipart form data with an image field

Response Format

The API returns a JSON response with the following structure:

{
  "texts": [
    "line1",
    "line2",
    "..."
  ]
}

Recommended Workflow

For the best results and user experience, follow this recommended integration workflow:

Examples

Consider this input image:

HTTP

> POST https://api.partium.io/1/find/ocr/detect
> Authorization: Bearer <<Your Access Token or API Key>>
> Content-Type: image/png
> Content-Length: 9053
>
> ...binary file...
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 51
<
< {
<   "texts": [
<     "Partium",
<     "has OcR!"
<   ]
< }
<

Python

with open('image.png', 'rb') as img_file: 
  ocr_response = requests.post(
    'https://api.partium.io/1/find/ocr/detect',
    headers={
      'Authorization': 'Bearer <<Your Access Token or API Key>>',
    },
    files={
      'image': (
          'image.png',
          img_file,
          'image/png',
          {},
      ),
    },
  )
  lines = ocr_response.json()['texts']
...

JavaScript

let lines = [];
let data = new FormData();
data.append('image', new Blob(image_binary_content, {type: 'image/png'}));
fetch('https://api.partium.io/1/find/ocr/detect', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <<Your Access Token or API Key>>',
  },
  body: data,
}).then(res => {
  lines = res.texts;
});
...

note

Replace <<Your Access Token or API Key>> with the preferred authentication method. See Authentication.

---

Additional Options

The OCR API supports additional configuration options through the input object in multipart form data requests. Currently, the following options are available:

Organization Selection

If your user has access to multiple organizations, you must specify the target organization in your request:

HTTP

> POST https://api.partium.io/1/find/ocr/detect
> Authorization: Bearer <<Your Access Token or API Key>>
> Content-Type: multipart/form-data; boundary=12dafc72cab
> Content-Length: 9053
>
> --12dafc72cab
> Content-Disposition: form-data; name="image"
> Content-Type: image/png
> 
> ...binary file...
> --12dafc72cab
> Content-Disposition: form-data; name="input"
> Content-Type: application/json
>
> {"organization": "<<Your organization name>>"}
> --12dafc72cab--
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 51
<
< {
<   "texts": [
<     "Partium",
<     "has OcR!"
<   ]
< }
<

Python

with open('image.png', 'rb') as img_file: 
  ocr_response = requests.post(
    'https://api.partium.io/1/find/ocr/detect',
    headers={
      'Authorization': 'Bearer <<Your Access Token or API Key>>',
    },
    files={
      'input': json.dumps({'organization': '<<Your organization name>>'}),
      'image': (
          'image.png',
          img_file,
          'image/png',
          {},
      ),
    },
  )
  lines = ocr_response.json()['texts']
...

JavaScript

let lines = [];
let data = new FormData();
data.append('image', new Blob(image_binary_content, {type: 'image/png'}));
data.append('input', JSON.stringify({ organization: '<<Your organization name >>' }));
fetch('https://api.partium.io/1/find/ocr/detect', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <<Your Access Token or API Key>>',
  },
  body: data,
}).then(res => {
  lines = res.texts;
});
...

note

Replace <<Your Access Token or API Key>> with your authentication token. See Authentication for more details.

---

Image Quality Guidelines

To achieve the best OCR results:

1. Image Resolution

   • Minimum resolution: 300 DPI
   • Recommended resolution: 600 DPI
   • Text should be clearly visible and not blurry

2. Lighting and Contrast

   • Ensure good lighting conditions
   • High contrast between text and background
   • Avoid shadows and glare

3. Text Orientation

   • Keep text horizontal when possible
   • Avoid extreme angles
   • Ensure text is not upside down

4. Image Cropping

   • Crop images to focus on the text area
   • Remove unnecessary background
   • Include small margins around text

Implementation Tips

1. Error Handling

   • Always implement proper error handling
   • Show meaningful error messages to users
   • Provide retry options when appropriate

2. User Experience

   • Show loading states during OCR processing
   • Allow users to preview and edit detected text
   • Provide clear feedback on success/failure

3. Performance

   • Optimize image size before upload
   • Consider implementing client-side image compression

4. Integration with Search

   • Use extracted text in relevant search contexts
   • Consider combining with other search modalities
   • Implement proper text normalization

Common Pitfalls to Avoid

1. Image Quality Issues

   • Sending blurry or low-resolution images
   • Poor lighting conditions
   • Excessive background noise

2. Implementation Mistakes

   • Not handling all error cases
   • Missing proper input validation
   • Ignoring rate limits

3. User Experience Problems

   • Not providing feedback during processing
   • Missing preview/confirmation steps
   • Poor error messaging

Error Handling

CODE	DESCRIPTION	HEADERS
400 - Bad Request	Invalid image format or missing required fields in the request.
401 - Unauthorized	No Authorization header was provided, or the provided credentials are invalid/unknown.	WWW-Authenticate: Describing the Authentication scheme
403 - Forbidden	The requested operation is not permitted with the provided credentials.
411 - Length Required	The Content-Length is required for the attempted operation but was missing or invalid.
413 - Request Entity Too Large	The maximum request payload size was exceeded. Check Limits & Constraints for more details.
429 - Too Many Requests	The current request rate exceeds the agreed limit. Check Limits & Constraints for more details.	Retry-After: Set to the earliest possible date for retrying the operation.
500 - Internal Server Error	An unexpected error occurred on the server.

Rate Limits

The OCR API is subject to rate limiting. Please contact support for specific rate limit information for your organization.