Docs/Map_Mode

Element Mapping Legacy

Extract the "Interactable Geometry" of any webpage. Precise coordinates for buttons, inputs, links, etc.

Compute Cost

2 Credits

performance mode

Latency

<400ms

global average

Precision

99.5%

element detection

The Geometry Engine

Map Mode transforms a DOM tree into a 2D coordinate system. Instead of raw HTML, you receive a flat list of Interactable Elements (Buttons, Inputs, Links) with their exact bounding box (x, y, w, h).

Performance Engine (Default)

2 Credits

Precision Engine

10 Credits

Implementation

Standard Request (Performance)

Fast rendering with Servo engine. 2 credits per request.

1curl -X POST https://api.sentienceapi.com/v1/observe \
2  -H "Authorization: Bearer sk_live_..." \
3  -H "Content-Type: application/json" \
4  -d '{
5    "url": "https://app.example.com/login",
6    "mode": "map"
7  }'

Precision Request

Pixel-perfect rendering with Headless Chrome. 10 credits per request.

SPA / React

1curl -X POST https://api.sentienceapi.com/v1/observe \
2  -H "Authorization: Bearer sk_live_..." \
3  -H "Content-Type: application/json" \
4  -d '{
5    "url": "https://app.example.com/login",
6    "mode": "map",
7    "options": {
8      "render_quality": "precision"
9    }
10  }'

Request with Visual Cues

NEW

Get visual styling hints (color names, cursor type, prominence) for icon-heavy UIs. Adds ~17 tokens per element.

1curl -X POST https://api.sentienceapi.com/v1/observe \
2  -H "Authorization: Bearer sk_live_..." \
3  -H "Content-Type: application/json" \
4  -d '{
5    "url": "https://figma.com/design/123",
6    "mode": "map",
7    "options": {
8      "include_visual_cues": true,
9      "limit": 200
10    }
11  }'

💡 Use Case: Perfect for icon-heavy UIs and design tools. Returns color names, cursor type, and prominence detection to help AI agents identify icon-only buttons and primary CTAs.

Smart Filtering

Reduce Noise by 95%

Large sites (Amazon/Reddit) return thousands of elements. Use filters to extract only what your agent needs (e.g., "Only big buttons").

Filter Strategy

limit: 100 (Top 100 important items)
min_area: 400 (Ignore tiny icons)
allowed_roles (Only buttons/inputs)

"options": {
  "limit": 50,
  "filter": {
    "min_area": 400,
    "allowed_roles": ["button", "link"]
  }
}

Output Schema

JSON Response

Example response with new fields: is_occluded (always included) and visual_cues (when include_visual_cues=true)

1{
2  "engine": "performance",
3  "status": "success",
4  "url": "https://app.example.com/login",
5  "layout_viewport": {
6    "width": 1024,
7    "height": 768,
8    "device_pixel_ratio": 1.0
9  },
10  "interactable_elements": [
11    {
12      "id": 1,
13      "uid": "username-input",
14      "tag": "input",
15      "role": "textbox",
16      "text": "",
17      "selector": "#username",
18      "bbox": {
19        "x": 100,
20        "y": 150,
21        "w": 300,
22        "h": 40
23      },
24      "is_visible": true,
25      "z_index": 0,
26      "in_viewport": true,
27      "is_occluded": false,
28      "attributes": {
29        "type": "text",
30        "placeholder": "Enter username"
31      }
32    },
33    {
34      "id": 2,
35      "uid": "login-submit",
36      "tag": "button",
37      "role": "button",
38      "text": "Sign In",
39      "selector": "button#login-submit",
40      "bbox": {
41        "x": 100,
42        "y": 320,
43        "w": 300,
44        "h": 48
45      },
46      "is_visible": true,
47      "z_index": 0,
48      "in_viewport": true,
49      "is_occluded": false,
50      "attributes": {
51        "type": "submit",
52        "aria_label": "Sign in to your account"
53      },
54      "visual_cues": {
55        "background_color_name": "blue",
56        "color_name": "white",
57        "cursor": "pointer",
58        "is_primary": true
59      }
60    }
61  ],
62  "timestamp": "2025-12-18T10:30:00.456Z",
63  "total_elements_extracted": 2,
64  "filters_applied": {
65    "limit": null,
66    "filter": null
67  }
68}

is_occluded: Always included. Indicates whether the element is covered by another element (detected via elementFromPoint raycasting).

visual_cues: Only included when include_visual_cues: true. Contains 4 fields: background_color_name, color_name, cursor, and is_primary.

← Back: Reader Mode Next: Visual Mode

Reader Mode

Visual Mode