PDF Get Words

PDF Get Words

Type: pdf-get-words  ·  Package: PDF Activities v1.2.4  ·  Output: List

Since: v1.1.0

Extracts every word of the PDF along with its page and its bounding box (position and size). It is the “with position” version of PDF Get Text: instead of a block of text, it tells you where each word is on the page.

How it works

Goes through the requested pages in ascending order and returns a flat list of words (not grouped by page or line): each item carries its own page number. To sort them by line, use y and then x. It doesn’t modify the file.

Coordinates use a top-left origin — the same as images and OCR. That way, the words returned by this activity and the lines returned by OCR Get Lines speak the same language, and you can locate a value on the page wherever it comes from.

By default coordinates are in PDF points (one point is 1/72 of an inch; an A4 sheet is about 595 × 842 points). If you set dpi, they are in pixels of a render at that resolution (points × dpi / 72): that makes them line up with the files produced by PDF To Images at the same dpi, so you can crop or draw on the image using these coordinates directly.

Needs a text layer

It only works with PDFs that have real selectable text. A scanned PDF has no words to extract and the list comes back empty: render it first with PDF To Images and use OCR Get Lines on the images.

Required parameters

Parameter	Type	Default	Description
path	string	—	Path of the PDF file.

Optional parameters

Parameter	Type	Default	Description
pages	string | List	"all"	Pages to read: "all" or a range such as "1-3,5,7-9", or a list of numbers such as the one from PDF Search Text. Since 1.2.4.
dpi	int	—	When set, coordinates are in pixels of a render at that resolution (they line up with PDF To Images at the same DPI). When omitted, in PDF points. Integer between 36 and 1200.

Output

Returns a List of dictionaries, one entry per word:

Key	Type	What it is
text	string	The word.
page	int	Page number (from 1).
x	number	Distance from the page’s left edge to the start of the word.
y	number	Distance from the page’s top edge to the top of the word.
width	number	Width of the word.
height	number	Height of the word.

The four measures are in PDF points, or in pixels if you set dpi, and have decimals. If the pages have no text, the list is empty.

[
  { "text": "TOTAL", "page": 1, "x": 72.0, "y": 640.5, "width": 38.2, "height": 9.1 },
  { "text": "1,250,000", "page": 1, "x": 450.3, "y": 640.5, "width": 52.8, "height": 9.1 }
]

Common errors

Message	Cause and fix
Page(s) out of range: …. The document has … pages.	The range asks for pages that don’t exist.
'dpi' must be an integer. Received: ….	dpi is not an integer (e.g. "200.5" or a text).
'dpi' must be between 36 and 1200. Received: ….	Resolution outside the supported range.
File not found. / 'path' is required.	See Common package errors.
PDF library error when opening the file	Password-protected or damaged PDF. See Protected and damaged PDFs.

Example

Render the PDF and extract the words with coordinates that match the images:

PDF To Images   path = invoicePath   outputDir = "C:/temp/pages"   dpi = 200   → output: images
PDF Get Words   path = invoicePath   dpi = 200   → output: words
Log   message = "Words: " + count(words)

Locate where a value appears on the page:

PDF Get Words   path = filePath   pages = "1"   → output: words
For Each   items = words   itemVariable = word
 └─ activities:
      If   condition = word["text"] == "TOTAL"
       └─ then:
            Log   message = "TOTAL is at x=" + word["x"] + " y=" + word["y"]

Related activities

• PDF Get Text — the text without coordinates.
• PDF To Images — render the pages to images at the same DPI.
• OCR Get Lines — the same, but for scanned PDFs and images.