Introduction
Welcome to the Polymer public API documentation!
The left side includes the endpoints description, method, URL, request/response schema, and description. The right side contains example requests (via curl) and responses (in JSON).
Most of the functionality available in the web application is covered by API. However, some use cases may not be available via API yet.
If this is your first time reading the docs, check out the Authentication section for obtaining and using API keys.
Authentication
Polymer API uses API keys to allow access to our endpoints. You can register a new API key inside user settings in the API Keys section.
You can create as many API Keys as you want and name them. Once you don't want to use it, you can disable or remove it from the dashboard.
You must include the API key in all requests to the server. There are two ways to include it:
As a query parameter: ?api_key=&your_api_key
As a header: X-API-KEY: &your_api_key
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
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 invalid. |
404 | Not Found -- Could not find the specified item. |
405 | Method Not Allowed -- You tried to access the API with an invalid method. |
429 | Too Many Requests -- You're making too many requests. |
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://api.polymersearch.com/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://api.polymersearch.com/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://api.polymersearch.com/v1/workspaces' \
--header 'accept: application/json, text/plain, */*' \
--header 'x-api-key: {{apikey}}'
HTTP Request
GET https://api.polymersearch.com/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://api.polymersearch.com/v1/workspace/64c25eae9797258e69dff54d' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
"name": "My Workspace Edited name"
}'
HTTP Request
PATCH https://api.polymersearch.com/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://api.polymersearch.com/v1/workspace/638da37174ea61d5d9b9a6c7' \
--header 'accept: application/json, text/plain, */*' \
--header 'x-api-key: {{apikey}}'
HTTP Request
DELETE https://api.polymersearch.com/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 |
Workspace_User
Fetch existing & invited workspace users
curl --location --request GET 'https://api.polymersearch.com/v1/workspace/users' \
--header 'accept: application/json, text/plain, */*' \
--header 'x-api-key: {{apikey}}'
HTTP Request
GET https://api.polymersearch.com/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://api.polymersearch.com/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://api.polymersearch.com/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://api.polymersearch.com/v1/workspace/user/638da37174ea61d5d9b9a6c7' \
--header 'accept: application/json, text/plain, */*' \
--header 'x-api-key: {{apikey}}'
HTTP Request
DELETE https://api.polymersearch.com/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 empowers you to create new Polymer sites from your CSV files effortlessly.
Upload a Dataset
This endpoint starts processing provided CSV.
curl --location --request POST 'https://api.polymersearch.com/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://api.polymersearch.com/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",
"import_from": {
"id": "6107ab93fa0ec85cb863f0e1",
"data": [
"views"
]
}
}'
curl --location --request POST 'https://api.polymersearch.com/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 yearly3.csv",
"import_from": {
"id": "6107ab93fa0ec85cb863f0e1",
"data": [
"views","user_config"
]
}
}'
curl --location --request POST 'https://api.polymersearch.com/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": "60f7bdd7c07d897637ac60f5"
}
HTTP Request
POST https://api.polymersearch.com/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. |
sharing | false | Desired sharing status for the dataset (public, password-protected, private). Defaults to private. |
password | false | Required only in case of sharing: password-protected, Validation: min 6 characters. |
header_row | false | Desired header row number (Min 1). |
starting_row | false | Desired row number where Polymer should start processing your file (Min 2). |
update | false | Boolean. Force update dataset in case a dataset already exists with the given name. |
styling.colors | false | List. List of color codes to be used in view preview mode. |
styling.font | false | String. One of the fonts from 'Helvetica', 'Arial', 'Times', 'Times New Roman', 'Courier', 'Courier New', 'Verdana', 'Tahoma', 'Arial Black', 'Comic Sans MS', 'Impact', 'Avant Garde', 'Georgia', 'Palatino', 'Bookman', 'Garamond', 'Century Schoolbook', 'Andale Mono'. |
Note: Either the 'url' or 'file' parameter is required.
Update a Dataset
Update the content and metadata of an existing dataset with this endpoint.
curl --location --request PUT 'https://api.polymersearch.com/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": "60f7bdd7c07d897637ac60f5"
}
HTTP Request
PUT https://api.polymersearch.com/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. |
sharing | false | Desired sharing status for the dataset (public, private, password-protected). |
password | false | Required only in case of sharing: password-protected, Validation: min 6 characters. |
incremental_update | In case you are passing incremental updates only | |
primary_key | Yes if incremental_update = true | name of the column |
styling.colors | false | List. List of color codes to be used in view preview mode. |
styling.font | false | String. One of the fonts from 'Helvetica', 'Arial', 'Times', 'Times New Roman', 'Courier', 'Courier New', 'Verdana', 'Tahoma', 'Arial Black', 'Comic Sans MS', 'Impact', 'Avant Garde', 'Georgia', 'Palatino', 'Bookman', 'Garamond', 'Century Schoolbook', 'Andale Mono'. |
Task
Fetch Status
curl --location --request GET 'https://api.polymersearch.com/v1/tasks/610805441afac351d4f2f2ad' \
--header 'accept: application/json, text/plain, */*' \
--header 'x-api-key: {{apikey}}'
The above command returns JSON structured like this:
{
"user_id": "644b656f5279d0d125043fdf",
"status": "Done",
"type": "dataset_upload",
"created_at": "2023-07-20T06:42:16.893Z",
"updated_at": "2023-07-20T06:42:17.482Z",
"data": {
"message": "file processing done",
"launch_url": "https://app.polymersearch.com/polymer/data/64b8d748c9afb894d91cfe83",
"embed_code": "<iframe height=\"1200\" scrolling=\"no\" src=\"https://app.polymersearch.com/polymer/data/64b8d748c9afb894d91cfe83\" style=\"overflow:hidden;height:100%;width:100%;position:absolute;top:0;left:0;right:0;bottom:0\" width=\"100%\"></iframe>",
"success": true,
"file_id": "64b8d748c9afb894d91cfe83"
},
"id": "64b8d748c9afb849f81cfe80"
}
HTTP Request
GET https://api.polymersearch.com/v1/tasks/:id
Body content
Field | Datatype | Description |
---|---|---|
status | String | If set to 'Done' then task is executed and you can find response in data key |
data.success | Boolean | If true then dataset was processed successfully and launch URL (data.launch_url) is ready |
data.launch_url | String | launch URL (data.launch_url), only if data.success is true |
data.embed_code | String | Embed Code (data.embed_code), only if data.success is true |
data.errors | List | List of errors, only if data.success is false |
View
The Views API allows you to create charts and data segments and share them with others. You can embed manually selected charts or let our powerful AI determine the best charts for your data.
Create View
Example 1: Create a basic view with all non-AI charts
curl --location --request POST 'https://api.polymersearch.com/v1/datasets/6278c1c221fb918ae401c228/view' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "My View Name",
"charts": [
{
"type": "pie",
"x_axis_multiple": [
{
"name": "payment_mechanism"
}]
"slice": "Submission Date"
},
{
"type": "bar",
"x_axis": "Fee Month",
"y_axis": "amount",
"slice": "Submission Date",
"operation": "AVERAGE"
}]
}'
Example 2: Create a basic view with all AI charts
curl --location --request POST 'https://api.polymersearch.com/v1/datasets/6278c1c221fb918ae401c228/view' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "AI view",
"charts": [
{
"type": "ai"
},
{
"type": "ai"
},
{
"type": "ai"
}]
}'
Example 3: Create a basic view with all AI and non-AI charts
curl --location --request POST 'https://api.polymersearch.com/v1/datasets/6278c1c221fb918ae401c228/view' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "AI View",
"charts": [
{
"type": "heatmap",
"x_axis": "Fee Month",
"y_axis": "amount",
"operation": "MAX"
},
{
"type": "ai"
},
{
"type": "ai"
},
{
"type": "ai"
}]
}'
The above command returns JSON structured like this:
{
"launch_url": "https://app.polymersearch.com/views/e793422c-71bf-4043-8363-5e5a4f551fc1",
"uid": "e793422c-71bf-4043-8363-5e5a4f551fc1"
}
HTTP Request
POST https://api.polymersearch.com/v1/datasets/:id/view
URL Params
Field | Mandatory | Description |
---|---|---|
id | true | Type: String Dataset ID |
Body content
Field | Mandatory | Description |
---|---|---|
name | true | Type: String Name of the view |
charts | true | Type: List [Chart Object] |
sharing | false | Desired sharing status for the dataset (public, private, password-protected). Default: private |
password | false | Required only in case of sharing: password-protected, Validation: min 6 characters. |
Chart Object
AI Chart
{
"type": "ai"
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | ai |
width | Boolean | No | Any value from one-third , two-thirds, full. Default: full |
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
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | bar |
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
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | column |
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
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | scatter |
x_axis | String | Yes | valid column name |
y_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 |
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
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | timeseries |
x_axis | String | Yes | valid column name |
y_axis | String | No | valid column name |
y_axis_multiple | List | No | Object, Min length: 2, Max length: 10. name: valid column operation: Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN |
operation | String | Yes | 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
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | heatmap |
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"
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | lineplot |
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
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | pie |
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 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 |
OUTLIERS
{
"type": "outliers",
"metric": "spend",
"operation": "COUNT",
"exclude_empty_string": false,
"influencing_columns": [
"ad_name"
]
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | outliers |
metric | String | Yes | valid 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 |
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
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | roi |
max_metric | String | Yes | Metric to Maximize (Return) - valid 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 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 |
PIVOT TABLE
{
"type": "pivot",
"metrics": [
{
"metric": "spend",
"operation": "SUM"
}],
"rows": [
"account_currency"
],
"columns": ["ad_name"]
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | pivot |
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 |
KPI BLOCK
{
"type": "kpi",
"metric": "impressions",
"operation": "SUM",
"date": "date",
"date_range": "last 90 days",
"goal": 4000000
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | kpi |
metric | List | Yes | valid 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 |
date_range_custom | List | No | If date_range is selected as custom. [START_DATE_EPOCH_SECONDS, END_DATE_EPOCH_SECONDS] |
comp_date_range | String | No | Any value from 'previous period', 'custom' |
comp_date_range_custom | List | No | If comp_date_range is selected as custom. [START_DATE_EPOCH_SECONDS, END_DATE_EPOCH_SECONDS] |
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"
}
}
Field | Datatype | Mandatory | Desc |
---|---|---|---|
type | String | Yes | data-table |
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_column_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
{
"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 View
Example 1: Edit view with all non-AI charts
curl --location --request PUT 'https://api.polymersearch.com/v1/datasets/views/dc2507ac-5e5d-456f-897f-e8ae23544b59' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"charts": [
{
"type": "timeseries",
"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"
}]
}'
Example 2: Edit view with all non-AI charts and name
curl --location --request PUT 'https://api.polymersearch.com/v1/datasets/views/dc2507ac-5e5d-456f-897f-e8ae23544b59' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Edited View Name",
"charts": [
{
"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://app.polymersearch.com/views/dc2507ac-5e5d-456f-897f-e8ae23544b59",
"uid": "dc2507ac-5e5d-456f-897f-e8ae23544b59"
}
HTTP Request
PUT https://api.polymersearch.com/v1/datasets/views/:view_uid
URL Params
Field | Mandatory | Description |
---|---|---|
view_uid | true | Type: String View UID |
Body content
Field | Mandatory | Description |
---|---|---|
name | false | Type: String Name of the view |
charts | false | Type: List [Chart Object] |
sharing | false | Desired sharing status for the dataset (public, private, password-protected). Default: private |
password | false | Required only in case of sharing: password-protected, Validation: min 6 characters. |
Charts Object
Same as described on Create View request
Note: Make sure you pass all the charts inside charts
key
Fetch Views
Response
{
"data": [
{
"uid": "40d4b950-78bb-4d6c-8b06-9fd20dbdf704",
"name": "component test Group view 1 4",
"sharing": "password-protected",
"launch_url": "https://app.polymersearch.com/views/6278c1c221fb918ae401c228/40d4b950-78bb-4d6c-8b06-9fd20dbdf704",
"file_id": "6278c1c221fb918ae401c228",
"user_id": "61ee36cf2ac79ae07f539bcf",
"created_at": "2022-09-13T10:35:28.349Z",
"updated_at": "2022-09-13T10:54:02.214Z"
},
{
"uid": "d85a90ec-ed66-432f-bdfa-488bf298ad7e",
"name": "component test Group view 1 3",
"sharing": "password-protected",
"launch_url": "https://app.polymersearch.com/views/6278c1c221fb918ae401c228/d85a90ec-ed66-432f-bdfa-488bf298ad7e",
"file_id": "6278c1c221fb918ae401c228",
"user_id": "61ee36cf2ac79ae07f539bcf",
"created_at": "2022-09-13T10:33:30.863Z",
"updated_at": "2022-09-13T10:33:30.863Z"
}],
"limit": 10,
"page": 1,
"sort_key": "created_at",
"sort_order": "desc"
}
HTTP Request
GET https://api.polymersearch.com/v1/datasets/views
Delete View
Response
{
"success": true
}
HTTP Request
DELETE https://api.polymersearch.com/v1/datasets/views/:view_uid
URL Params
Field | Mandatory | Description |
---|---|---|
view_uid | true | Type: String View UID |
App_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:
Request
curl --location 'https://api.polymersearch.com/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"
}
As soon as you have the auth token, you can pass this token to embed URL/src.
https://app.polymersearch.com/${file_id}?token={token}