Appearance
getData() Contract
The getData() function is how AddMaple widgets access your data. You implement this function and pass it to the embed component.
Overview
getData() is an async function that returns:
- Dataset metadata (columns, row count)
- Preview rows for browser-mode analysis
- Optional
serverFetchURL for full server-mode analysis
The embed calls getData() once on mount and again before server-mode analysis if needed.
Response Schema
json
{
"datasetId": "dataset_123",
"datasetType": "survey",
"n_rows": 512,
"columns": [
{ "name": "satisfaction", "type": "numeric" },
{ "name": "age", "type": "numeric" },
{ "name": "comment", "type": "text" },
{ "name": "would_recommend", "type": "boolean" }
],
"previewRows": [
{ "satisfaction": "8", "age": "34", "comment": "Loved it", "would_recommend": "true" },
{ "satisfaction": "6", "age": "28", "comment": "Good but slow", "would_recommend": "true" }
],
"serverFetch": {
"url": "https://partner.example.com/addmaple/full-data/tf_123",
"method": "GET",
"headers": { "Authorization": "Bearer abc123" },
"expiresAt": "2025-12-01T11:15:00Z"
}
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
Field Reference
Required Fields
| Field | Type | Description |
|---|---|---|
datasetId | string | Unique dataset identifier |
columns | array | Column definitions with name and type |
previewRows | array | Sample rows for browser-mode analysis |
Optional Fields
| Field | Type | Description |
|---|---|---|
datasetType | string | Hint about data source (e.g., survey, crm, support) |
n_rows | number | Total row count in full dataset |
serverFetch | object | URL for AddMaple to fetch full dataset |
Column Types
| Type | Description |
|---|---|
numeric | Numbers, percentages, currencies |
category | Categorical/enum values |
text | Free-form text responses |
boolean | True/false values |
serverFetch Object
| Field | Type | Description |
|---|---|---|
url | string | Required. URL AddMaple will call for full data |
method | string | HTTP method (default: GET) |
headers | object | Optional headers to include |
expiresAt | string | ISO timestamp when URL expires |
Implementation Examples
Basic: Server-Backed getData()
The recommended approach — your server fetches data and returns the response:
js
async function getData() {
const res = await fetch('/api/addmaple/get-embed-data?datasetId=dataset_123', {
credentials: 'include'
})
if (!res.ok) throw new Error('Failed to get data')
return res.json()
}1
2
3
4
5
6
7
2
3
4
5
6
7
js
// Express.js example
app.get('/api/addmaple/get-embed-data', async (req, res) => {
const { datasetId } = req.query
// Fetch data from your source (SaaS API, database, etc.)
const rows = await fetchSourceRows(datasetId)
// Create preview (sanitize PII if needed)
const preview = rows.slice(0, 150)
// Optionally create a signed URL for full data access
const serverFetch = await createSignedUrl(datasetId)
res.json({
datasetId,
datasetType: 'survey',
n_rows: rows.length,
columns: detectColumns(rows),
previewRows: preview,
serverFetch
})
})1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
With Signed URL (S3 Presigned)
For large datasets, provide a presigned S3 URL:
js
app.get('/api/addmaple/get-embed-data', async (req, res) => {
const { datasetId } = req.query
// Generate presigned S3 URL (expires in 15 minutes)
const presignedUrl = await s3.getSignedUrl('getObject', {
Bucket: 'my-data-bucket',
Key: `datasets/${datasetId}.csv`,
Expires: 900
})
res.json({
datasetId,
columns: await getColumnSchema(datasetId),
previewRows: await getPreviewRows(datasetId, 150),
serverFetch: {
url: presignedUrl,
method: 'GET',
expiresAt: new Date(Date.now() + 900000).toISOString()
}
})
})1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
Without serverFetch (Browser-Only)
If you don't provide serverFetch, only browser-mode analysis is available:
js
async function getData() {
return {
datasetId: 'local_dataset',
columns: [
{ name: 'score', type: 'numeric' },
{ name: 'category', type: 'category' }
],
previewRows: myLocalData.slice(0, 200)
// No serverFetch — browser-mode only
}
}1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
Browser Mode Limitations
Without serverFetch:
- Only heuristic analysis on preview rows
- AI Chat is unavailable
- Lower fidelity results for large datasets
Best Practices
Preview Rows
- Include 100-200 rows for good browser-mode results
- Sanitize PII unless user has consented
- Include a representative sample (not just the first N rows)
Columns
- Always include
nameandtypefor each column - Use accurate types — this affects analysis quality
- Include all columns the user might want to analyze
serverFetch URLs
- Use short-lived URLs (15-60 minutes)
- Prefer presigned URLs over embedding credentials
- Consider IP allowlisting for partner endpoints
- Return data in CSV or JSON format
Error Handling
If getData() throws or returns invalid data, the embed will:
- Emit a
getData_erroranalytics event - Show an error state to the user
- Not attempt server-mode analysis
js
async function getData() {
try {
const res = await fetch('/api/data')
if (!res.ok) throw new Error(`HTTP ${res.status}`)
return res.json()
} catch (error) {
// Log error to your system
console.error('getData failed:', error)
throw error // Re-throw so embed knows it failed
}
}1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11