Blueprints / Drawing text

List the words printed on a sheet

Every word printed on the sheet: its text, its position as fractions (0..1) of the page from the top-left corner, where it was read (the PDF's own text or text recognition) and the room it is printed in. Use it to search a drawing's text, or to read what is written inside one room or one region.

Words come in a fixed stored order, limit per page; total counts every word that matches the filters, and next_cursor continues the same read until it is null. rooms maps each room_id on the page to the room's name.

The sheet's state is never an error: status is ok, empty (read, and nothing is printed), not_read (never read: its words are unknown, not absent) or unavailable (try again later), with a note. With room_id, rooms_unknown means it is not known which words are in that room, never that the room is empty. A word whose room_id is null is outside every room only when room_links_status is ok.

404 when the sheet is not in one of your projects. 422 for an unknown field or source, a malformed bbox, a room_id that is not a room on this sheet, or a cursor from another sheet or other filters.

get/v1/blueprints/{blueprint_id}/words

Request

  • Base URL: https://api.kamai.io (the document declares no server; this is the origin it was published from)
  • URL: https://api.kamai.io/v1/blueprints/{blueprint_id}/words
  • Auth: HTTP bearer

Path parameters

blueprint_idstring required

Query parameters

qstring nullable

Only words containing this text, case-insensitive. It is matched inside one word: a phrase is printed as several words, so search each word on its own.

room_idstring nullable

Only words printed inside this room: the room's feature id (as in GET /v1/blueprints/{id}) or a room_id a word returned.

sourcestring[] nullable

Only words from these sources: digital, ocr or ocr_bubble; repeat it or pass a comma list.

bboxstring nullable

Only words inside this region: x0,y0,x1,y1 in fractions (0..1) of the page from the top-left corner, x1 > x0 and y1 > y0. A word is inside when the centre of its box is.

fieldsstring nullable

Per-word fields, comma-separated. The whole list, not extras: when given it replaces the default text, bbox, source, room. Also: rot, conf, polygon, id, wall, room_name.

cursorstring nullable

next_cursor of the previous page. Valid only with the same filters.

limitinteger nullable

Words per page; 2,000 when left out.

Response

Successful Response

status'ok' | 'empty' | 'not_read' | 'unavailable' | 'rooms_unknown' required

ok; empty: read, and nothing is printed; not_read: never read, so the words are unknown, not absent; unavailable: could not be read just now, try again; rooms_unknown (with room_id only): which words are in that room is unknown, which does NOT mean the room is empty.

notestring nullable

A plain-English explanation whenever the answer is not a plain ok.

frame'page_fraction'

Every position is a fraction (0..1) of the page, from the top-left corner.

pageobject nullable

The page's width and height in PDF points (1/72 inch).

countsobject nullable

Words on the whole sheet per source, before any filter.

totalinteger nullable

Words matching the filters, across all pages; null when unknown.

next_cursorstring nullable

Pass it as cursor for the next page; null on the last page.

roomsobject nullable

Each room_id on this page mapped to the room's name.

room_links_status'ok' | 'not_indexed' | 'unavailable' nullable

Whether words' rooms are known: ok; not_indexed: the sheet's text is not linked to rooms (not processed yet, or processed before the page size changed); unavailable: could not be read just now.

Changes

No recorded changes to this operation across all 1 revision of this API.