Introduction
Welcome to the Polymer public API documentation! You can use our API to access Polymer API endpoints, that provide various functionality present on our website.
Endpoints description, method, URL, request/response schema, and their description are presented on the left. The right side contains example requests (via curl) and responses (in JSON). In the future, more endpoints will be added to provide complete access to Polymer database.
If this is your first time reading the docs, check out the Authentication section for obtaining and using API keys.
The Changelog section contains all updates related to this API.
Authentication
Polymer API uses API keys to allow access to our endpoints. You can register a new API key as a user, inside user settings, on the API Keys section.
Currently you can create as many API Keys as you want and give them a name. Once you don't want to use it you can disable it from the dashboard.
Polymer API expects the API key to be included in all API requests to the server. There are two ways to include it in requests:
As a query parameter: ?api_key=&your_api_key
As a header: X-API-KEY: &your_api_key
Please note that the "workspace-id" header is optional. It is only necessary when you intend to execute an operation within a workspace other than the default one defined by the APIKEY.
Rate Limiting
All Polymer APIs have rate limiting implemented. A single API key can make up to 100 requests per hour. After reaching the rate limit, HTTP Status 429 - Too Many Requests will be returned.
Response headers contain rate-limiting details:
- X-RateLimit-Limit: Number of requests you can make in an hour
- X-RateLimit-Remaining: Number of requests left for the time window
- X-RateLimit-Reset: The remaining window before the rate limit resets in UTC epoch seconds
Currently there is no rate limiting per user, but it may be introduced in future updates.
Errors
The Polymer API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request is invalid. |
401 | Unauthorized -- Your API key is wrong. |
404 | Not Found -- The specified item could not be found. |
405 | Method Not Allowed -- You tried to access the API with an invalid method. |
429 | Too Many Requests -- You're making too many request. |
500 | Internal Server Error -- We had a problem with our server. Try again later. |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |
Workspace
Create a new workspace
curl --location --request POST 'https://v3.polymersearch.com/api/v1/workspace' \
--header 'accept: application/json, text/plain, */*' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "My Workspace Name",
"slug": "workspace-slug"
}'
HTTP Request
POST https://v3.polymersearch.com/api/v1/workspace
Body content
Field | Mandatory | Description |
---|---|---|
name | true | Name of the workspace. |
slug | true | slug to be used in custom URLs. Alphanumeric characters, underscores, and dashes are allowed. It cannot end with an underscore or a dash. |
Get workspaces
curl --location --request GET 'https://v3.polymersearch.com/api/v1/workspaces' \
--header 'accept: application/json, text/plain, */*' \
--header 'x-api-key: {{apikey}}'
HTTP Request
GET https://v3.polymersearch.com/api/v1/workspaces
The above command returns JSON structured like this:
{
"data": [
{
"_id": "636e0856759be73b280cfa11",
"slug": "api-demo",
"name": "Polymer's Workspace",
"default_name_unedited": true,
"user_role": "Creator",
"default": true,
"members": [
{
"_id": "636e0856759be7e1f00cfa0f",
"name": "Polymer Search",
"email": "[email protected]"
}
]
},
{
"_id": "638850663e5ca0629efc34ed",
"name": "Marketing",
"slug": "polymer-marketing",
"user_role": "Creator",
"default": false,
"members": [
{
"_id": "636e0856759be7e1f00cfa0f",
"name": "Polymer Search",
"email": "[email protected]"
},
{
"_id": "638b60eb3dc9fa2645946403",
"name": "Remo",
"email": "[email protected]"
},
{
"_id": "6390cdea9a51cd0743387a6e",
"name": "Ras",
"email": "[email protected]"
}
]
}
]
}
Edit workspace
curl --location --request PATCH 'https://v3.polymersearch.com/api/v1/workspace/64c25eae9797258e69dff54d' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
"name": "My Workspace Edited name"
}'
HTTP Request
PATCH https://v3.polymersearch.com/api/v1/workspace/:id
Body content
Field | Mandatory | Description |
---|---|---|
name | false | Name of the workspace. |
slug | false | slug to be used in custom URLs. Alphanumeric characters, underscores, and dashes are allowed. It cannot end with an underscore or a dash. |
Delete workspace
curl --location --request DELETE 'https://v3.polymersearch.com/api/v1/workspace/638da37174ea61d5d9b9a6c7' \
--header 'accept: application/json, text/plain, */*' \
--header 'x-api-key: {{apikey}}'
HTTP Request
DELETE https://v3.polymersearch.com/api/v1/workspace/:id
The above command returns JSON structured like this:
{
"success": true
}
URL Params
Field | Mandatory | Description |
---|---|---|
id | true | Type: String _id field from '/v1/workspaces' response |
Users
Fetch existing & invited workspace users
curl --location --request GET 'https://v3.polymersearch.com/api/v1/workspace/users' \
--header 'accept: application/json, text/plain, */*' \
--header 'x-api-key: {{apikey}}'
HTTP Request
GET https://v3.polymersearch.com/api/v1/workspace/users
The above command returns JSON structured like this:
{
"data": [
{
"_id": "636e0856759be7e1f00cfa0f",
"name": "Polymer Search",
"email": "[email protected]",
"role": "Creator"
},
{
"_id": "6389db43daeaa35b76482b14",
"name": "Name User",
"email": "[email protected]",
"role": "Editor"
},
{
"_id": "638da37174ea61d5d9b9a6c7",
"name": "Sam Title",
"email": "[email protected]",
"role": "Read-only"
},
{
"role": "Read-only",
"_id": "63ec8c9a41f84c7d02ee344e",
"email": "[email protected]",
"pending": true,
"invitation_id": "63ec8c9a41f84c7d02ee344e"
}
]
}
Invite a new member to workspace
curl --location --request POST 'https://v3.polymersearch.com/api/v1/workspace/invite' \
--header 'accept: application/json, text/plain, */*' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"members": [
{
"email": "[email protected]",
"role": "Read-only"
}
]
}'
HTTP Request
POST https://v3.polymersearch.com/api/v1/workspace/invite
The above command returns JSON structured like this:
{
"success": true,
"invited": true
}
Body content
Field | Mandatory | Description |
---|---|---|
members | true | List of members to invite |
members[].email | true | valid email ID |
members[].role | true | Valid values: Editor, Read-only |
skip_invite_email | false | Boolean |
Delete existing or invited workspace user
curl --location --request DELETE 'https://v3.polymersearch.com/api/v1/workspace/user/638da37174ea61d5d9b9a6c7' \
--header 'accept: application/json, text/plain, */*' \
--header 'x-api-key: {{apikey}}'
HTTP Request
DELETE https://v3.polymersearch.com/api/v1/workspace/user/:wuid
The above command returns JSON structured like this:
{
"message": "user deleted successfully"
}
URL Params
Field | Mandatory | Description |
---|---|---|
wuid | true | Type: String _id field from '/v1/workspace/users' response |
Dataset
The Dataset API allows the creation of new Polymer sites from your CSV files.
Upload a Dataset
This endpoint starts processing provided CSV.
curl --location --request POST 'https://v3.polymersearch.com/api/v1/dataset' \
--header 'x-api-key: XXd5c7f6-XXf9-4320-XX4d-5673d8XXd5bb' \
--header 'Content-Type: application/json' \
--data-raw '{
"url": "https://abcc.s3.amazonaws.com/myfile.csv",
"name": "Payment yearly.csv",
"starting_row": 10,
"update": true
}'
curl --location --request POST 'https://v3.polymersearch.com/api/v1/dataset' \
--header 'x-api-key: XXd5c7f6-feXX-43XX-XX4d-5673d8f0d5XX' \
--header 'Content-Type: application/json' \
--data-raw '{
"url": "https://abcc.s3.amazonaws.com/myfile.csv",
"name": "Payment yearly2.csv"
}'
curl --location --request POST 'https://v3.polymersearch.com/api/v1/dataset' \
--header 'x-api-key: XXd5c7f6-feXX-43XX-XX4d-5673d8f0d5XX' \
--header 'Content-Type: application/json' \
--data-raw '{
"ingestion_type": "json",
"name": "Payment yearly3.csv",
"records": [
{
"ticket_id": "ID2",
"created_at": "2022-10-21",
"language": "Spanish",
"number1": 14
},{
"ticket_id": "ID2",
"created_at": "2022-10-21",
"language": "Spanish",
"number1": 14
}
]
}'
curl --location --request POST 'https://v3.polymersearch.com/api/v1/dataset' \
--header 'x-api-key: XXd5c7f6-feXX-43XX-XX4d-5673d8f0d5XX' \
--form 'name="Payment yearly 2022 920.csv"' \
--form 'file=@"/local_file_path/file_name.csv"'
The above command returns JSON structured like this:
{
"task_id": "65c3249d63a20b6727a11127"
}
HTTP Request
POST https://v3.polymersearch.com/api/v1/dataset
Body content
Field | Mandatory | Description |
---|---|---|
url | false | URL to a valid public downloadable CSV. |
file | false | Type: file. The file to upload. |
name | true | Name of the dataset/file. |
starting_row | false | Desired row number where Polymer should start processing your file. |
update | false | Boolean. Force update dataset in case a dataset already exists with the given name. |
Note: Either 'url' or 'file' parameter is required.
Update a Dataset
This endpoint updates the content and metadata of an existing dataset.
curl --location --request PUT 'https://v3.polymersearch.com/api/v1/dataset/6151754dfad3627deeb8f84b' \
--header 'x-api-key: XXeca66c-21f3-XX39-b407-64e00c62XXXX' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "FB Ad List Q2 C-uploaded.csv",
"url": "https://test-csv-datasets.s3.us-east-2.amazonaws.com/Test+-+Bank+Loans.csv"
}'
The above command returns JSON structured like this:
{
"task_id": "65c324f463a20b6727a1116b"
}
The above command returns JSON structured like this:
{
"success": false,
"errors": [
{
"message": "duplicate file name"
}
]
}
HTTP Request
PUT https://v3.polymersearch.com/api/v1/dataset/:id
Params content
Field | Mandatory | Description |
---|---|---|
id | true | Dataset ID. |
Body content
Field | Mandatory | Description |
---|---|---|
url | false | URL to a valid public downloadable CSV. |
file | false | Type: file. The file to upload. |
name | false | Name of the dataset/file. |
incremental_update | In case you are passing incremental updates only | |
primary_key | Yes if incremental_update = true | name of the column |
Fetch Datasets
This endpoint returns list of datasets
curl --location --request PUT 'https://v3.polymersearch.com/api/v1/dataset' \
--header 'x-api-key: XXeca66c-21f3-XX39-b407-64e00c62XXXX' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "FB Ad List Q2 C-uploaded.csv",
"url": "https://test-csv-datasets.s3.us-east-2.amazonaws.com/Test+-+Bank+Loans.csv"
}'
The above command returns JSON structured like this:
{
"data": [
{
"_id": "65d775c6428356ae03b21b1f",
"user": "65d775a24283563f98b21a75",
"user_email": "[email protected]",
"name": "11_payment 624 CSV copy 1114.csv",
"source_type": "upload",
"workspace_id": "65d775a24283564ab4b21a81",
"created_at": "2024-02-22T16:26:46.352Z",
"extension": "csv",
"num_rows": 59626,
"status": "success",
"id": "65d775c6428356ae03b21b1f"
},
{
"_id": "65d778bc4283568b69b221ef",
"user": "65d775a24283563f98b21a75",
"user_email": "[email protected]",
"name": "DS1",
"source_type": "api",
"workspace_id": "65d775a24283564ab4b21a81",
"extension": "csv",
"created_at": "2024-02-22T16:39:24.358Z",
"num_rows": 5,
"status": "success",
"id": "65d778bc4283568b69b221ef"
},
{
"_id": "65ddabc9428356050bb89426",
"user": "65d775a24283563f98b21a75",
"user_email": "[email protected]",
"name": "File upload demo dataset",
"source_type": "api",
"workspace_id": "65d775a24283564ab4b21a81",
"extension": "csv",
"created_at": "2024-02-27T09:30:49.830Z",
"num_rows": 5,
"status": "success",
"id": "65ddabc9428356050bb89426"
}],
"limit": 100,
"page": 1,
"sort_key": "name",
"sort_order": "asc"
}
HTTP Request
GET https://v3.polymersearch.com/api/v1/dataset
Query string
Field | Mandatory | Description |
---|---|---|
limit | false | Page limit. |
page | false | Page number. |
sort_key | false | name, created_at, num_rows |
sort_order | false | desc,asc |
Task
Fetch Status
curl --location --request GET 'https://v3.polymersearch.com/api/v1/task/65c324f463a20b6727a1116b' \
--header 'accept: application/json, text/plain, */*' \
--header 'x-api-key: {{apikey}}'
The above command returns JSON structured like this:
{
"file_id": "65c32d8334632067c1d32d18",
"status": "inprogress"
}
{
"file_id": "65bc94d3cdb8f39435d3e21a",
"status": "done"
}
{
"status": "done",
"error": "An error has occurred (processing timeout). Our team is looking into it."
}
HTTP Request
GET https://v3.polymersearch.com/api/v1/task/:id
Body content
Field | Datatype | Description |
---|---|---|
status | String | If set to 'done' then task is executed and you can find file_id. If set to 'inprogress' please poll again in 5 seconds |
error | String | if we encounter any processing error |
Board
With boards API you can create blocks and data segments and share them with the world instead of exposing the complete Polymer site. Embed in your site a manually selected block for your data, or let our powerful AI determine what are the best blocks for your data.
Create Board
Example 1: Create a basic board with 2 blocks
curl --location --request POST 'https://v3.polymersearch.com/api/v1/board' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Sample Board 1",
"file_ids": [
"65b50541d83d1e4d42c7fbe0"
],
"sharing": "public",
"advanced_sharing":
{
"allow_global_filters_for_viewers": false,
"allow_block_based_filters_for_viewers": true
},
"filters":
{},
"blocks": [
{
"type": "kpi",
"metric": "time_spent_in_days",
"operation": "SUM",
"date": "solved_at",
"date_range": "last 90 days",
"goal": 1000,
"file_id": "65b50541d83d1e4d42c7fbe0",
"comp_date_range": "previous month"
},
{
"type": "data-table",
"columns": [
"ticket_group"
],
"values": [
{
"column": "time_spent_in_minutes",
"operation": "SUM"
}],
"sort":
{
"column": "time_spent_in_minutes",
"order": "DESC"
},
"show_totals": false,
"file_id": "65b50541d83d1e4d42c7fbe0"
}
]
}'
The above command returns JSON structured like this:
{
"launch_url": "https://v3.polymersearch.com/b/6409bc2ae761d55b4630989b",
"id": "6409bc2ae761d55b4630989b"
}
HTTP Request
POST https://v3.polymersearch.com/api/v1/board
Body content
Field | Mandatory | Description |
---|---|---|
name | true | Type: String Name of the board |
file_ids | true | Type: List[String] Dataset IDs of the board |
blocks | true | Type: List [Blocks Object] |
sharing | false | Desired sharing status for the dataset (public, private). Default: private |
advanced_sharing | false | control sharing settings for board |
advanced_sharing.allow_global_filters_for_viewers | false | Type: Boolean Viewers would be able to apply global filters |
advanced_sharing.allow_block_based_filters_for_viewers | false | Type: Boolean Viewers would be able to apply block based filters |
branding.logoUrl | false | Logo URL |
branding.logoLink | false | Link to redirect when clicked on logo URL |
colors | false | Type: List List of color codes to be used in view preview mode. |
auto_generated | false | Type: Boolean Auto generted board |
Blocks Object
Bar Chart
{
"type": "bar",
"x_axis_multiple": [
{
"name": "spend",
"operation": "SUM"
},
{
"name": "Clicks (all)",
"operation": "COUNT"
}],
"y_axis": "campaign_status",
"operation": "SUM",
"y_axis_log": true,
"show_annotations": true,
"show_stacked": false,
"file_id": "65b50541d83d1e4d42c7fbe0"
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | bar |
file_id | String | Yes | file ID to drive this block |
x_axis | List | one of the x_axis or x_axis_multiple is required | valid column name |
x_axis_multiple | List | one of the x_axis or x_axis_multiple is required | Object, Min length: 2, Max length: 10. name: valid column operation: Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN |
y_axis | String | Yes | valid column name |
operation | String | No | Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN |
sort | Object | No | type: total (Total), raw (Raw Order), count (Count), value (x-axis tags) operation: Any value from asc, desc |
slice | String | No | valid column name |
show_annotations | Boolean | No | Annotate each segment by its value |
show_stacked | Boolean | No | Show as stack. Default: true |
is_percentage | Boolean | No | Show as percentage |
y_axis_log | Boolean | No | Use logarithmic scale for Y-Axis |
exclude_empty_string | Boolean | No | Exclude [EMPTY] strings. Default: true |
width | Boolean | No | Any value from one-third , two-thirds, full. Default: full |
filters | Object | No | Filter Object |
title | String | No | Custom heading |
Column Chart
{
"type": "column",
"x_axis": "campaign_status",
"y_axis_multiple": [
{
"name": "spend",
"operation": "SUM"
},
{
"name": "Clicks (all)",
"operation": "COUNT"
}],
"operation": "SUM",
"show_annotations": true,
"show_stacked": false,
"file_id": "65b50541d83d1e4d42c7fbe0"
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | column |
file_id | String | Yes | file ID to drive this block |
x_axis | String | Yes | valid column name |
y_axis | String | one of the y_axis or y_axis_multiple is required | valid column name |
y_axis_multiple | List | one of the y_axis or y_axis_multiple is required | Object, Min length: 2, Max length: 10. name: valid column operation: Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN |
operation | String | No | Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN |
sort | Object | No | type: total (Total), raw (Raw Order), count (Count), value (x-axis tags) operation: Any value from asc, desc |
slice | String | No | valid column name |
show_annotations | Boolean | No | Annotate each segment by its value |
show_stacked | Boolean | No | Show as stack. Default: true |
is_percentage | Boolean | No | Show as percentage |
x_axis_log | Boolean | No | Use logarithmic scale for X-Axis |
exclude_empty_string | Boolean | No | Exclude [EMPTY] strings. Default: true |
width | Boolean | No | Any value from one-third , two-thirds, full. Default: full |
filters | Object | No | Filter Object |
title | String | No | Custom heading |
SCATTER PLOT Chart
{
"type": "scatter",
"x_axis": "spend",
"y_axis": "cost_per_initiate_checkout",
"operation": "SUM",
"x_axis_log": true,
"file_id": "65b50541d83d1e4d42c7fbe0"
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | scatter |
file_id | String | Yes | file ID to drive this block |
x_axis | String | Yes | valid number column name |
y_axis | String | Yes | valid number column name |
operation | String | Yes | Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN |
slice | String | No | valid column name |
x_axis_log | Boolean | No | Use logarithmic scale for X-Axis |
y_axis_log | Boolean | No | Use logarithmic scale for Y-Axis |
exclude_empty_string | Boolean | No | Exclude [EMPTY] strings. Default: true |
width | Boolean | No | Any value from one-third , two-thirds, full. Default: full |
filters | Object | No | Filter Object |
title | String | No | Custom heading |
TIMESERIES Chart
{
"type": "timeseries",
"x_axis": "date",
"operation": "SUM",
"y_axis_log": true,
"exclude_empty_string": false,
"group_by": "quarter",
"is_area": true,
"file_id": "65b50541d83d1e4d42c7fbe0"
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | timeseries |
file_id | String | Yes | file ID to drive this block |
x_axis | String | Yes | valid date column name |
y_axis | String | No | valid number column name |
y_axis_multiple | List | No | Object, Min length: 2, Max length: 10. name: valid number column operation: Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN |
slice | String | No | valid column name |
is_area | Boolean | No | Use area chart |
y_axis_log | Boolean | No | Use logarithmic scale for Y-Axis |
exclude_empty_string | Boolean | No | Exclude [EMPTY] strings. Default: true |
group_by | String | No | Any value from day, week, month, quarter, year |
width | Boolean | No | Any value from one-third , two-thirds, full. Default: full |
filters | Object | No | Filter Object |
title | String | No | Custom heading |
HEATMAP Chart
{
"type": "heatmap",
"y_axis": "account_currency",
"operation": "SUM",
"exclude_empty_string": false,
"show_annotations": true,
"file_id": "65b50541d83d1e4d42c7fbe0"
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | heatmap |
file_id | String | Yes | file ID to drive this block |
y_axis | String | Yes | valid column name |
x_axis | String | No | valid column name |
operation | String | Yes | Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN |
slice | String | No | valid column name |
show_annotations | Boolean | No | Annotate each segment by its value |
exclude_empty_string | Boolean | No | Exclude [EMPTY] strings. Default: true |
width | Boolean | No | Any value from one-third , two-thirds, full. Default: full |
filters | Object | No | Filter Object |
title | String | No | Custom heading |
LINEPLOT Chart
{
"type": "lineplot",
"x_axis": "spend",
"y_axis": "link_click",
"operation": "SUM",
"file_id": "65b50541d83d1e4d42c7fbe0"
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | lineplot |
file_id | String | Yes | file ID to drive this block |
y_axis | String | one of the y_axis or y_axis_multiple is required | valid column name |
y_axis_multiple | List | one of the y_axis or y_axis_multiple is required | Object, Min length: 2, Max length: 10. name: valid column operation: Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN |
x_axis | String | Yes | valid column name |
operation | String | Yes | Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN |
slice | String | No | valid column name |
y_axis_log | Boolean | No | Use logarithmic scale for Y-Axis |
exclude_empty_string | Boolean | No | Exclude [EMPTY] strings. Default: true |
width | Boolean | No | Any value from one-third , two-thirds, full. Default: full |
filters | Object | No | Filter Object |
title | String | No | Custom heading |
PIE Chart
{
"type": "pie",
"x_axis_multiple": [
{
"name": "status"
}],
"exclude_empty_string": false,
"show_annotations": true,
"file_id": "65b50541d83d1e4d42c7fbe0"
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | pie |
file_id | String | Yes | file ID to drive this block |
x_axis_multiple | List | Yes | Object, Min length: 1, Max length: 2. name: valid column |
y_axis_multiple | List | No | Object, Min length: 1, Max length: 1. name: valid number column operation: Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN |
show_annotations | Boolean | No | Annotate each segment by its value |
exclude_empty_string | Boolean | No | Exclude [EMPTY] strings. Default: true |
width | Boolean | No | Any value from one-third , two-thirds, full. Default: full |
filters | Object | No | Filter Object |
title | String | No | Custom heading |
OUTLIER
{
"type": "outlier",
"metric": "spend",
"operation": "COUNT",
"exclude_empty_string": false,
"influencing_columns": [
"ad_name"
],
"file_id": "65b50541d83d1e4d42c7fbe0"
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | outlier |
file_id | String | Yes | file ID to drive this block |
metric | String | Yes | valid number column name |
operation | String | Yes | Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN |
influencing_columns | List | Yes | Influencing Columns - list of valid column names. Min length: 1, Max length: 6 |
results_type | String | No | Show results - Any value from count, below_average_only, above_average_only, top_and_bottom_outliers, above_and_below_average |
show_results_column | Boolean | No | Show Results Column |
exclude_empty_string | Boolean | No | Exclude [EMPTY] strings |
width | Boolean | No | Any value from one-third , two-thirds, full. Default: full |
filters | Object | No | Filter Object |
title | String | No | Custom heading |
lower_better | Boolean | No | Lower Better |
ROI CALCULATOR
{
"type": "roi",
"max_metric": "impressions",
"max_operation": "AVERAGE",
"min_metric": "spend",
"min_operation": "MAX",
"influencing_columns": [
"ad_name",
"campaign_name"
],
"show_results_column": false,
"file_id": "65b50541d83d1e4d42c7fbe0"
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | roi |
file_id | String | Yes | file ID to drive this block |
max_metric | String | Yes | Metric to Maximize (Return) - valid number column name |
max_operation | String | Yes | Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN |
min_metric | String | Yes | Metric to Minimize (Investment) - valid number column name |
min_metric | String | Yes | Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN |
influencing_columns | List | Yes | Influencing Columns - list of valid column names. Min length: 1, Max length: 6 |
show_results_column | Boolean | No | Show Results Column |
show_percentage | Boolean | No | Show ROI as Percentage |
exclude_empty_string | Boolean | No | Exclude [EMPTY] strings |
width | Boolean | No | Any value from one-third , two-thirds, full. Default: full |
filters | Object | No | Filter Object |
title | String | No | Custom heading |
lower_better | Boolean | No | Lower Better |
PIVOT TABLE
{
"type": "pivot",
"metrics": [
{
"metric": "spend",
"operation": "SUM"
}],
"rows": [
"account_currency"
],
"columns": ["ad_name"],
"file_id": "65b50541d83d1e4d42c7fbe0"
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | pivot |
file_id | String | Yes | file ID to drive this block |
metrics | List | Yes | Object, Min length: 1, Max length: 10. metric: valid column operation: Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN |
rows | List | Yes | Rows - list of valid column names. Min length: 1, Max length: 1 |
columns | List | Yes | Columns - list of valid column names. Min length: 1, Max length: 1 |
show_row_totals | Boolean | No | Show Row Totals |
show_column_totals | Boolean | No | Show Column Totals |
show_percentage | Boolean | No | Show Percentage, Default: True |
sort_by_row_tags | String | No | Sort rows by tag value. Any value from ASC, DESC |
column_manual_order | List | No | Sort columns by column tags. List of tag values |
sort_by_counts | Object | No | column_index: index of the column given in columns metric_index: index of the column given in metrics order: Any value from ASC, DESC |
width | Boolean | No | Any value from one-third , two-thirds, full. Default: full |
filters | Object | No | Filter Object |
title | String | No | Custom heading |
pin_totals | Boolean | No | Pin Totals |
KPI BLOCK
{
"type": "kpi",
"metric": "impressions",
"operation": "SUM",
"date": "date",
"date_range": "last 90 days",
"goal": 4000000,
"file_id": "65b50541d83d1e4d42c7fbe0"
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | kpi |
file_id | String | Yes | file ID to drive this block |
metric | List | Yes | valid date column name |
operation | String | Yes | Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN |
date | String | No | valid date column name |
date_range | String | No | Any value from 'last day', 'last 7 days', 'last 14 days', 'last 30 days', 'last 90 days', 'last 6 months', 'last 12 months, 'this month', 'this week', 'last week', custom |
comp_date_range | String | No | Any value from 'previous period', 'custom' |
goal | Number | No | |
exclude_empty_string | Boolean | No | Exclude [EMPTY] strings |
width | Boolean | No | Any value from one-third , two-thirds, full. Default: full |
filters | Object | No | Filter Object |
DATA TABLE
{
"type": "data-table",
"columns": [
"ticket_group"
],
"values": [
{
"column": "time_spent_in_minutes",
"operation": "SUM"
}],
"sort":
{
"column": "time_spent_in_minutes",
"order": "DESC"
},
"file_id": "65b50541d83d1e4d42c7fbe0"
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | data-table |
file_id | String | Yes | file ID to drive this block |
columns | List | Yes | valid column name |
values | List | Yes | Object, Min length: 1, Max length: 10. column: valid column operation: Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN |
sort | Object | Yes | Object column: valid column order: Any value from ASC, DESC |
exclude_empty_string | Boolean | No | Exclude [EMPTY] strings |
show_totals | Boolean | No | Show Column Totals |
width | Boolean | No | Any value from one-third , two-thirds, full. Default: full |
filters | Object | No | Filter Object |
title | String | No | Custom heading |
RICH TEXT
{
"type": "rich-text-insight",
"html": "<p><strong>This is just a header</strong></p><p><i>Add blocks of <u>your choice</u></i></p>"
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | rich-text-insight |
html | String | Yes | HTML text |
width | Boolean | No | Any value from one-third , two-thirds, full. Default: full |
Field: filters
Allowed values: object
The following filters can be applied
- Filter date columns with dynamic date range like last 30 days, last year, etc.
- Filter numerical columns with ranges like amount between 25 to 45.
- Text search in categorical columns like payment mechanism including cash and demand draft.
- Text search in categorical columns like payment mechanism excluding cash
Example payload
{
"65b50541d83d1e4d42c7fbe0":
{
"Submission Date": [
{
"value": "last 30 days"
}],
"amount": [
{
"value": [
10,
20
]
}],
"Payment Mechanism": [
{
"value": "cash",
"operation": "INCLUDING"
}]
}
}
The following filter will be read as
Submission Date within last 30 days
AND
amount between range 10 to 20
AND
Payment Mechanism INCLUDING cash
Possible dynamic date ranges:
- last day
- last 7 days
- last 14 days
- last 30 days
- last 90 days
- last 6 months
- last 12 months
- last week
- this week
- this month
Possible operations:
- INCLUDING
- EXCLUDING
Edit Board
Example 1: Edit board with blocks
curl --location --request PUT 'https://v3.polymersearch.com/api/v1/board/63f36125bfc81986e3cbd2c3' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"blocks": [
{
"type": "timeseries",
"x_axis": "payment_mechanism",
"y_axis": "Submission Date",
"slice": "amount"
},
{
"type": "bar",
"x_axis": "Fee Month",
"y_axis": "amount",
"slice": "Submission Date",
"operation": "MIN"
}]
}'
Example 2: Edit board with blocks and name
curl --location --request PUT 'https://v3.polymersearch.com/api/v1/board/63f36125bfc81986e3cbd2c3' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Edited Board Name",
"blocks": [
{
"type": "bar",
"x_axis": "payment_mechanism",
"y_axis": "Submission Date",
"slice": "amount",
"operation": "SUM"
},
{
"type": "bar",
"x_axis": "Fee Month",
"y_axis": "amount",
"slice": "Submission Date",
"operation": "MIN"
}]
}'
The above command returns JSON structured like this:
{
"launch_url": "https://v3.polymersearch.com/b/6409bc2ae761d55b4630989b",
"id": "6409bc2ae761d55b4630989b"
}
HTTP Request
PUT https://v3.polymersearch.com/api/v1/board/:board_id
URL Params
Field | Mandatory | Description |
---|---|---|
board_id | true | Type: String Board ID |
Body content
Field | Mandatory | Description |
---|---|---|
name | false | Type: String Name of the board |
blocks | false | Type: List [Blocks Object] |
sharing | false | Desired sharing status for the dataset (public, private). Default: private |
advanced_sharing | false | control sharing settings for board |
advanced_sharing.allow_global_filters_for_viewers | false | Type: Boolean Viewers would be able to apply global filters |
advanced_sharing.allow_block_based_filters_for_viewers | false | Type: Boolean Viewers would be able to apply block based filters |
branding.logoUrl | false | Logo URL |
branding.logoLink | false | Link to redirect when clicked on logo URL |
colors | false | Type: List List of color codes to be used in view preview mode. |
Blocks Object
Same as described on Create Board request
Note: Make sure you pass all the blocks inside blocks
key
Fetch Boards
Response
{
"data": [
{
"_id": "63f36125bfc81986e3cbd2c3",
"created_at": "2023-02-20T12:01:41.730Z",
"updated_at": "2023-02-20T12:01:41.730Z",
"uid": "abf3a195-4135-4471-9d24-ab2acde3e45a",
"user_id": "636e0856759be7e1f00cfa0f",
"file_id": "63d8248de061fa0d2023f20a",
"name": "board - 1",
"sharing": "public",
"is_template": "false"
},
{
"_id": "6409bb0be045c05b1fccb721",
"created_at": "2023-03-09T10:55:07.578Z",
"updated_at": "2023-03-09T10:55:07.578Z",
"uid": "52f0ecfa-9545-4a0b-8e7f-8d47c1aefcb9",
"user_id": "636e0856759be7e1f00cfa0f",
"file_id": "6409b295e0eb635a29d8c8f7",
"name": "Board with advanced_sharing",
"sharing": "public",
"advanced_sharing": {
"allow_global_filters_for_viewers": false,
"allow_block_based_filters_for_viewers": true
}
},
{
"_id": "6409bc2ae761d55b4630989b",
"created_at": "2023-03-09T10:59:54.313Z",
"updated_at": "2023-03-09T10:59:54.313Z",
"uid": "7ce8918b-441e-4ee1-8977-970b47ea9b68",
"user_id": "636e0856759be7e1f00cfa0f",
"file_id": "6409b295e0eb635a29d8c8f7",
"name": "Board with advanced_sharing11",
"sharing": "public",
"advanced_sharing": {
"allow_global_filters_for_viewers": false,
"allow_block_based_filters_for_viewers": true
}
}
],
"limit": 10,
"page": 1,
"sort_key": "created_at",
"sort_order": "asc"
}
HTTP Request
GET https://v3.polymersearch.com/api/v1/boards
Delete Board
Response
{
"success": true
}
HTTP Request
DELETE https://v3.polymersearch.com/api/v1/board/:board_id
URL Params
Field | Mandatory | Description |
---|---|---|
board_id | true | Type: String Board ID |
Embed
Polymer generated app can be embed to create new boards (views), and browse/edit existing ones:
Generate an auth token
This endpoint generates token to give authenticated access to embeded apps:
HTTP Request
GET https://v3.polymersearch.com/api/v1/auth/token?access_level=${permission_level}
Query string
Field | Mandatory | Description |
---|---|---|
permission_level | true | board_read_only : Grant permission for reading data from the specified board ID. board_edit : Grant permission for reading/editing data from the specified board ID. workspace_read_only: Authorize access for reading (read-only) all board data within the workspace. workspace_edit : Grant permission for reading, adding, and editing all board data within the workspace. block_level_read_only : Grant permission for reading data from the specified block from board ID. |
board_id | false | Required when granting board_read_only, block_level_read_only or board_edit permissions. |
Request
curl --location 'https://v3.polymersearch.com/api/v1/auth/token?access_level=workspace_edit' \
--header 'x-api-key: XXd5c7f6-XXf9-4320-XX4d-5673d8XXd5bb' \
--header 'workspace-id: 64XX73dd2221f86XXbc934XX'
Note: workspace-id header is optional and only needed when you want to generate auth-token for a specific workspace which is different than default workspace defined with APIKEY
The above command returns JSON structured like this:
{
"token": "XXXX72f4-df9c-XX6e-92XX-XXX09f41XX",
"expires_at": "2023-07-20T12:15:40.741Z"
}
Generating an embed URL using an authentication token
https://v3.polymersearch.com/b/${board_id}?ptoken={token}