post https://api.similarweb.com/batch/v4/request-validate
Validates a request prior to submission and provides an approximate estimate of the report's cost.
Request:
Body Params
| Property | Description | Type |
|---|---|---|
| report_query | Report query parameters. | ReportQuery |
| delivery_information | Delivery information parameters. | DeliveryInformation |
ReportQuery Object
| Property | Description | Type |
|---|---|---|
| tables | List of tables to query. | List[TableQuery] |
TableQuery Object
| Property | Description | Type |
|---|---|---|
| vtable | Mandatory. Select the table you would like to query from. | String |
| granularity | Mandatory. Select the data granularity. Can be 'daily', 'weekly' or 'monthly'. | String |
| filters | A list of filters applied to the table. | QueryFilter |
| metrics | A list of metrics representing the columns in your report. | List[String] |
| start_date | Specifies the start date. Use the format YYYY-MM for monthly granularity, and YYYY-MM-DD for weekly or daily granularity. | String |
| end_date | Specifies the end date. Use the format YYYY-MM for monthly granularity, and YYYY-MM-DD for weekly or daily granularity. | String |
| latest | Optional. When enabled, it overrides the end_date with the last available date. | Boolean |
| all_history | Optional. When enabled, it overrides the end_date with the last available date and the start_date with the first available date. | Boolean |
| window_size | Optional. Sets the start_date by subtracting the specified window from the end_date. The window can be specified using "d" for days, "m" for months, and "y" for years. For example, "3m" will subtract 3 months from the end_date to determine the start_date. | String |
| paging | Set pagination configuration. | PagingConfig |
QueryFilter Object
Note:
Different filters are available for each table and can be selected accordingly. The applicable filters for a specific table can be found under 'table_filters' in the discovery endpoint for the requested table.
PagingConfig Object
| Property | Description | Type |
|---|---|---|
| limit | Optional. default value varies per "vtable". | Integer |
| offset | Optional. default is 0. Set the offset. | Integer |
| sort | Optional. Set the metric you want the report to be sorted upon. by default takes the first metric specified. | String |
| sort_asc | Optional. default is False. Decides if to sort ascending or descending. | String |
DeliveryInformation Object
| Property | Description | Type |
|---|---|---|
| delivery_method | Set the Delivery Method. | Enum[download_link,bucket_access,snowflake] |
| response_format | Mandatory only for "download_link" and "bucket_access" delivery methods. Set the File format of the generated report. | Enum[json,csv,parquet,orc] |
| webhook_url | Optional. Set a webhook url to trigger when the report status is changed. | String |
| delivery_method_params | Optional. only relevant for delivery methods - "snowflake" and "bucket_access". Set delivery method configurations. | DeliveryMethodPropsRequest |
DeliveryMethodPropsRequest Object
| Property | Description | Type |
|---|---|---|
| integration_name | Optional. Only relevant in case of multiple set integrations. | String |
| table_name | Optional. if set pushes the data into a specific table. | String |
| retention_days | Optional. Specifies how long data is retained, with a default of 30 days. Can be set to 1, 30, 60, 180, or 365 days. | Integer |
| num_of_files | Optional. Relevant only for delivery_method "bucket_access". Sets the number of generated files. must be greater then zero. | String |
| write_mode | Optional. Accepted value: 'overwrite' - used when working with an S3 table to replace data for specific dates. | String |
Traffic & Engagement Table:
vtable: "traffic_and_engagement"
Table URL: https://api.similarweb.com/batch/v4/request-report
Primary Keys: domains, countries
| Metric Name | Description | Supported Granularity | Type |
|---|---|---|---|
| all_traffic_visits, desktop_visits, mobile_visits | Returns estimated number of visits for the domain. | Monthly, Weekly, Daily | Double |
| all_page_views, desktop_page_views, mobile_page_views | Returns the total number of pageviews for the selected domain. | Daily | Double |
| all_traffic_pages_per_visit, desktop_pages_per_visit, mobile_pages_per_visit | Returns the average page views per visit for the given domain. | Monthly, Weekly, Daily | Double |
| all_traffic_average_visit_duration, desktop_average_visit_duration, mobile_average_visit_duration | Returns the average visit duration on the given domain (in seconds). | Monthly, Weekly, Daily | Double |
| all_traffic_bounce_rate, desktop_bounce_rate, mobile_bounce_rate | Returns the bounce rate for the given domain. | Monthly, Weekly, Daily | Double |
| deduplicated_audience | Returns the average number of individuals who visited across desktop and mobile. | Monthly | Double |
| desktop_unique_visitors, mobile_unique_visitors | Returns unique desktop/mobile visitors. | Monthly, Daily | Double |
| desktop_share mobile_share | Returns the desktop/mobile web traffic share split. | Monthly | Double |
| desktop_ppc_spend_usd, mobile_ppc_spend_usd | Returns an estimation of the domain spending on PPC search terms on desktop/mobile. | Monthly | Double |
| desktop_new_visitors | Returns the count of unique users who have visited the site from a desktop device and have not been recorded on the site in the last three months. | Monthly | Double |
| desktop_returning_visitors | Returns the count of unique users who revisit the site from a desktop device within a three month period. | Monthly | Double |
| global_rank | Returns SimilarWeb's monthly Global Rank for a given domain. | Monthly | Integer |
| country_rank | Returns SimilarWeb's monthly Country Rank for a given domain. | Monthly | Integer |
| category_rank_new | Returns the Global Rank within its given category. | Monthly | Integer |
| category | Returns the top category associated with the domain. | Monthly | String |