> ## Documentation Index > Fetch the complete documentation index at: https://developers.gonitro.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Text Bounding Boxes > Locate specific strings in a PDF with the Nitro API and return the bounding box coordinates for each match. The Extract Text Bounding Boxes method of the Extractions endpoint lets you locate text in PDF files and retrieve its position on the page. It takes a list of queries as part of the `queries` parameter — each query is either literal text or a regular expression — and returns, for each query, the matches found in the PDF file along with their bounding boxes. It is useful to identify specific information in a document and identify locations for applying redactions. Each query accepts: `text`: The text or regular expression to search for. `isRegex`: Whether `text` should be treated as a regular expression. Defaults to `false`. `regexFlags`: Optional regex matching flags, only allowed when `isRegex` is `true`. Any combination of `ignore-case`, `multiline` and `dot-all`. Matching is exact and case-sensitive. For case-insensitive matching, use a regex query with the `ignore-case` flag. An invalid regular expression, or `regexFlags` on a non-regex query, is rejected with a `422` error explaining the problem. The response contains, under `textBoxes`, one result per query in the same order as the request. Each result echoes the `query` and lists its `matches`: `matchedText`: The full matched text. `boxes`: The bounding boxes covering the match — one per line, so a match spanning multiple lines yields multiple boxes. Each box has a zero-based `pageIndex`, a `boundingBox` as an array of four values (check the [Bounding Box Guide](/build-nitro/bounding-box)) and a `textPiece` with the text covered by that box. `groups`: For regex queries, the capture groups of the match, each with its one-based `index`, captured `text` and its own `boxes`. #### Example If you pass the parameters `queries: [{"text": "token"}, {"text": "conversions"}]` the method would identify the following boxes in the PDF file below: To find every amount of money following the word "Total", case-insensitively, you could pass: ```json theme={null} { "queries": [ { "text": "total:?\\s*\\$(\\d+(?:\\.\\d{2})?)", "isRegex": true, "regexFlags": ["ignore-case"] } ] } ``` The amount itself is returned as capture group `1` of each match, with its own bounding boxes. ### Output File Format The endpoint can return output either as JSON or as a binary file. The format depends on the `Accept` header (details below), which defaults to application/json. ### Processing When requesting JSON, you can run the operation synchronously or asynchronously. This is determined by the `Prefer` header (details below). * In sync mode, the response includes a URL pointing to the processed file. * In async mode, the request creates a Job, and the response contains the Job ID and status so you can track progress. Binary (octet-stream) responses are only available for synchronous operations. ### Custom File Delivery The endpoint supports custom file-delivery destinations through the optional delivery parameter. You can provide an upload target, such as your own PUT endpoint or a pre-signed S3 URL, and Nitro will upload the resulting file there. This works for both synchronous and asynchronous processing. * ### Sync delivery In synchronous calls, the [delivery](#body-delivery) parameter lets you direct Nitro to upload the output file to a custom URL endpoint or a pre-signed URL (e.g S3), by providing an upload url in the `uploadResultTo` or `uploadResultsTo` properties. #### Custom endpoint If implementing the upload endpoint by yourself, make sure your code or middleware configuration accepts requests without content-type headers. #### S3 delivery If you are using S3 to manage delivery uploads, follow this [AWS documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html) to generate a pre-signed PUT URL. If using the AWS provided Python script, omit the `Content-Type` in Params to get the pre-signed url. For example: ```python theme={null} url = generate_presigned_url( s3_client, "put_object", { "Bucket": args.bucket, "Key": args.key, # Content-Type: "application/octet-stream" => Omit! }, 1000) ``` * ### Async delivery In asynchronous flows, you can also provide a custom URL or pre-signed S3 object via `uploadResultTo` or `uploadResultsTo`, to upload your file(s) once the Job is done processing. #### Callback For asynchronous processing, you can also include a [callback](#body-delivery-callback) URL within the delivery parameter. This callback is a POST endpoint that Nitro will call once the Job is created and running, providing details about the file-processing job. Example of Nitro’s callback request body: ```json theme={null} { "jobID": "babe2aa7-9b5d-4eb2-a679-5fc12cf0a490", "location": "https://api.gonitro.dev/jobs/babe2aa7-9b5d-4eb2-a679-5fc12cf0a490" } ``` #### Response behavior Matrix This matrix shows the expected response behavior based on content type, sync/async mode, and custom file-delivery settings. | | **JSON (`application/json`)** | **Binary (`application/octet-stream`)** | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | **Synchronous** | Returns a JSON object with a file(s) URL(s). | Returns the processed file directly as binary. | | **Asynchronous (`respond-async`)** | Returns a JSON object with a Job ID and status. | Async preference ignored, returns sync binary. | | **Synchronous delivery** | File delivered to custom endpoint / Bucket, returns success confirmation. | N/A | | **Asynchronous delivery** | Returns a JSON object with a Job ID and status. The file(s) will be uploaded to the provided PUT endpoint / S3 Bucket at the end of process. If `callback` url is provided, Nitro will notify the endpoint with a JOB ID and location. | N/A | #### Limits The Platform API has the following limits: * File size: Maximum of 100 MB per request. This applies to single-file and multi-file requests. * Page count: Maximum of 500 pages per individual document. This applies to single-file and multi-file requests. Multiple documents may exceed 500 pages in total. * Retention time: Inputs and outputs are deleted approximately 15 minutes after the operation completes. ### Request ## OpenAPI ````yaml text-box POST /extractions openapi: 3.0.3 info: title: Nitro API - Document Intelligence Platform description: >- Consolidated API for document intelligence operations including conversions, extractions, transformations, and job management. **Supported Operations:** - **Conversions**: PDF ↔ MS Office, Images ↔ PDF, Various formats to PDF - **Extractions**: Text extraction, PII detection, Bounding box extraction, PDF properties - **Transformations**: Rotate, Split, Merge, Flatten, Password protection, Redaction - **Jobs**: Asynchronous processing with status monitoring and result retrieval **Global Limits:** - Maximum file size: 100MB - Maximum number of pages: 500 version: 1.0.0 contact: name: Nitro API Support url: https://help.gonitro.com/support servers: - url: https://api.gonitro.dev description: API server security: [] tags: - name: Conversions description: >- Document format conversion operations including PDF to/from MS Office, images, and various other formats - name: Extractions description: >- Data extraction operations for text, metadata, PII detection, and bounding box information - name: Transformations description: >- PDF transformation operations including rotation, splitting, merging, compression, protection, and redaction - name: Generations description: >- Document generation operations such as filling PDF AcroForm fields from a data file or inline values - name: Jobs description: >- Asynchronous job management for monitoring, retrieving results, and canceling long-running operations paths: /extractions: post: tags: - Extractions summary: Extract Text Boxes from PDF description: >- Locate literal text or regular expression matches in a PDF document and return their bounding boxes parameters: - name: Accept in: header schema: $ref: '#/components/schemas/AcceptHeader' - name: Prefer in: header schema: $ref: '#/components/schemas/PreferHeader' requestBody: required: true content: multipart/form-data: schema: type: object properties: method: type: string description: >- The Extractions' endpoint method: `extract-text-bounding-boxes` default: extract-text-bounding-boxes enum: - extract-text-bounding-boxes params: $ref: '#/components/schemas/TextboxExtractionParams' file: $ref: '#/components/schemas/FileUpload' delivery: $ref: '#/components/schemas/DeliverySingleFileOut' required: - method - params - file responses: '200': description: >- Returns either JSON or binary output depending on the Accept header (defaults to JSON). JSON responses include a file URL for synchronous tasks or a job status for asynchronous tasks. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ExtractTextBoxResponse' - $ref: '#/components/schemas/AsyncJobResponse' application/octet-stream: schema: type: string format: binary '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '413': $ref: '#/components/responses/ContentTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' security: - BearerAuth: [] components: schemas: AcceptHeader: type: string enum: - application/json - application/octet-stream - '*/*' default: '*/*' description: >- Controls response format and behavior. See endpoint description above for detailed response combinations. - `application/json`: Returns JSON response with operation result - `application/octet-stream`: Returns binary file content - `*/*`: Defaults to JSON response PreferHeader: type: string enum: - respond-async description: >- Controls synchronous vs asynchronous operation. See endpoint description above for behavior details. - `respond-async`: Makes request asynchronous, returns job status for polling - No value: Synchronous response TextboxExtractionParams: title: Text Box type: object properties: queries: type: array items: $ref: '#/components/schemas/TextBoxQuery' description: Array of queries to search for in the PDF file. required: - queries FileUpload: description: >+ The file to process. It can be provided as a binary upload or as a JSON remote file reference. oneOf: - type: string format: binary description: |- #### Binary file Standard multipart file binary upload field - type: object title: Remote file properties: URL: type: string format: uri description: URL of the remote file to process contentType: type: string description: The MIME type of the remote file example: application/pdf required: - URL - contentType description: |- #### Remote file JSON objects containing file URL and content type, sent with specific multipart encoding: `type` and `filename`. The playground **doesn't support** them. Plase test with an alternative tool (Ex: Postman). Example cURL file field for remote file: ```bash --form 'file={ "URL":"https://your-file.pdf", "contentType":"application/pdf" } ;type=application/vnd.gonitro.url+json ;filename=https://your-file.pdf' ``` DeliverySingleFileOut: type: object properties: uploadResultTo: $ref: '#/components/schemas/HTTPCall' callback: $ref: '#/components/schemas/Callback' description: >- This endpoint lets you supply your own URL to receive the single-file output. The URL may point to a custom API endpoint or a pre-signed S3 URL. The HTTP method defaults to PUT, but you can change it based on your implementation needs via the `verb` parameter. You can also provide custom headers, such as authentication headers or any others required by your endpoint. ExtractTextBoxResponse: type: object title: Sync - Text Box properties: result: $ref: '#/components/schemas/TextBoxResultType' required: - result AsyncJobResponse: type: object title: Async - Job properties: jobID: type: string example: 01234567-89ab-cdef-0123-456789abcdef status: type: string enum: - running progress: type: number description: Progress of the job as a float between 0.0 and 1.0 format: float default: 0 example: 0 TextBoxQuery: type: object properties: text: type: string description: The text or regular expression to search for. example: John Doe isRegex: type: boolean default: false description: Whether `text` should be treated as a regular expression. regexFlags: type: array uniqueItems: true items: type: string enum: - ignore-case - multiline - dot-all description: Regex matching flags; only allowed when `isRegex` is `true`. required: - text HTTPCall: type: object properties: URL: type: string description: Your delivery endpoint URL nullable: false format: uri verb: type: string description: The HTTP method default: PUT enum: - GET - POST - PUT - DELETE - PATCH headers: type: array nullable: true description: Headers your file delivery endpoint might need (Optional) items: $ref: '#/components/schemas/Header' required: - URL - verb Callback: type: object description: >- POST endpoint that will get JOB ID and location when processing starts only on async processesing (see example above) properties: URL: type: string description: Your POST endpoint callback URL. nullable: false format: uri headers: type: array description: Headers your callback endpoint might need items: $ref: '#/components/schemas/Header' required: - URL TextBoxResultType: type: object title: Text Boxes properties: textBoxes: type: array items: $ref: '#/components/schemas/TextBoxQueryResult' description: One result per query, in the same order as the request's `queries`. required: - textBoxes BadRequestProblemDetail: type: object description: Bad Request error details example: type: https://developers.gonitro.com/docs/build-nitro/errors#400-bad-request title: Bad Request status: 400 detail: Request validation failed instance: /platform/extractions allOf: - $ref: '#/components/schemas/ErrorResponse' UnauthorizedProblemDetail: type: object description: Unauthorized error details example: type: >- https://developers.gonitro.com/docs/build-nitro/errors#401-unauthorized title: Unauthorized status: 401 detail: Missing or invalid Authorization header instance: /platform/extractions allOf: - $ref: '#/components/schemas/ErrorResponse' NotFoundProblemDetail: type: object description: Not Found error details example: type: https://developers.gonitro.com/docs/build-nitro/errors#404-not-found title: Not Found status: 404 detail: Resource not found instance: /platform/extractions allOf: - $ref: '#/components/schemas/ErrorResponse' ContentTooLargeProblemDetail: type: object description: Content too large error details example: type: >- https://developers.gonitro.com/docs/build-nitro/errors#413-content-too-large title: Content too large status: 413 detail: Uploaded document exceeds the file size limit instance: /platform/extractions allOf: - $ref: '#/components/schemas/ErrorResponse' UnprocessableEntityProblemDetail: type: object description: Unprocessable Entity error details example: type: >- https://developers.gonitro.com/docs/build-nitro/errors#422-unprocessable-entity title: Unprocessable Entity status: 422 detail: The request was well-formed but could not be processed instance: /platform/extractions allOf: - $ref: '#/components/schemas/ErrorResponse' InternalServerErrorProblemDetail: type: object description: Internal Server Error details example: type: >- https://developers.gonitro.com/docs/build-nitro/errors#500-internal-server-error title: Internal Server Error status: 500 detail: An unexpected error occurred instance: /platform/extractions allOf: - $ref: '#/components/schemas/ErrorResponse' Header: type: object properties: name: type: string value: type: string required: - name - value TextBoxQueryResult: type: object properties: query: $ref: '#/components/schemas/TextBoxQuery' matches: type: array items: $ref: '#/components/schemas/TextBoxMatch' description: All matches found for the query, empty if the query did not match. required: - query - matches ErrorResponse: type: object properties: type: type: string description: A URI reference that identifies the problem type title: type: string description: A short, human-readable summary of the problem type status: type: integer format: int32 description: The HTTP status code detail: type: string description: A human-readable explanation specific to this occurrence instance: type: string description: A URI reference that identifies the specific occurrence TextBoxMatch: type: object properties: matchedText: type: string description: The full matched text. example: Scope of Services boxes: type: array items: $ref: '#/components/schemas/TextBoxBox' description: The bounding boxes covering the match, one per line of text. groups: type: array items: $ref: '#/components/schemas/TextBoxGroup' description: >- For regex queries, the capture groups of the match. Empty for literal queries. required: - matchedText - boxes - groups TextBoxBox: type: object properties: pageIndex: type: integer description: Page index where the text was found (0-based). boundingBox: type: array items: type: number minItems: 4 maxItems: 4 description: >- Bounding box coordinates in points [x, y, width, height]. Check the [Bounding Box Guideline](/build-nitro/bounding-box). example: - 200 - 100 - 100 - 20 textPiece: type: string description: The text covered by this box (a single line of the match). required: - pageIndex - boundingBox - textPiece TextBoxGroup: type: object properties: index: type: integer description: One-based index of the capture group within the regular expression. example: 1 text: type: string description: The text captured by the group. boxes: type: array items: $ref: '#/components/schemas/TextBoxBox' description: The bounding boxes covering the group, one per line of text. required: - index - text - boxes responses: BadRequest: description: Bad Request - Invalid request parameters content: application/problem+json: schema: $ref: '#/components/schemas/BadRequestProblemDetail' Unauthorized: description: Unauthorized - Invalid or missing Authorization header content: application/problem+json: schema: $ref: '#/components/schemas/UnauthorizedProblemDetail' NotFound: description: Not Found - Resource not found content: application/problem+json: schema: $ref: '#/components/schemas/NotFoundProblemDetail' ContentTooLarge: description: Content Too Large - File size exceeds limit content: application/problem+json: schema: $ref: '#/components/schemas/ContentTooLargeProblemDetail' UnprocessableEntity: description: Unprocessable Entity - Request cannot be processed content: application/problem+json: schema: $ref: '#/components/schemas/UnprocessableEntityProblemDetail' InternalServerError: description: Internal Server Error - An unexpected error occurred content: application/problem+json: schema: $ref: '#/components/schemas/InternalServerErrorProblemDetail' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ````