# Big Data Analytics Source: https://docs.ezoic.com/docs/api/bdaservices/ The Big Data Analytics (BDA) API lets your server pull the same reports and analytics data you see in your Ezoic dashboard. There are two kinds of reports: **predefined** reports that ship with your account, and **custom** reports you build yourself. See [API](/docs/api/) for how to enable the service, your base URL, and authentication. All examples below use your `developerKey`. ## Getting Started The easiest way to start is to pull the list of predefined reports with `getreports`: ```bash curl -X GET "https://api-gateway.ezoic.com/bdaservices/getreports/?developerKey=YOUR_API_KEY" ``` This returns a list of report names. We'll use the `revenueDaily` report. Look at its definition with `getreport`: ```bash curl -X GET "https://api-gateway.ezoic.com/bdaservices/getreport/?reportName=revenueDaily&developerKey=YOUR_API_KEY" ``` ## Getting Data Now pull the data with `getdata`. Because `revenueDaily` (like most predefined reports) has the `DateBaseSelectId` of `BASE_NOT_SELECTED` (no built-in date range), you must include a date range in the request. `getdata` requires a `MaxItems` value; some reports (for example when using URL as a dimension) return thousands of rows, so paginate by incrementing `StartItem`. `DateGrouping` controls whether data is grouped by day, week, or month. `Platform` chooses between `Ezoic`, `Orig`, or `ALL` (combined). `SegmentIds` is optional and splits a single row into multiple segments. ```bash curl -X POST "https://api-gateway.ezoic.com/bdaservices/getdata/?reportName=revenueDaily&developerKey=YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "StartItem": 0, "MaxItems": 10, "Platform": "ALL", "DomainId": 9999, "DateGrouping": "DAILY", "SegmentIds": [1], "StartDate": "2018-10-01", "EndDate": "2018-10-01" }' ``` ## Custom Reports To change which columns you get back, build a custom report. You can base it on a predefined report's definition. Get the list of available columns with `getcolumns`: ```bash curl -X GET "https://api-gateway.ezoic.com/bdaservices/getcolumns/?developerKey=YOUR_API_KEY" ``` This example adds a `copy_paste_per_pageview` column to a revenue report. You can also embed segments directly in the report: if a custom report has segments, `getdata` defaults to those when no segments are specified; otherwise the `getdata` request's segments take precedence. Setting the date range `BaseSelectId` to `BASE_LAST_7` means a `getdata` request with no dates defaults to the last seven days. ```bash curl -X POST "https://api-gateway.ezoic.com/bdaservices/createcustomreport/?developerKey=YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "ReportTitle": "My Custom Revenue Report", "ReportDateRange": { "BaseSelectId": "BASE_LAST_7" }, "Charts": [ { "Name": "My Custom Revenue Report Chart", "DimensionColumns": [ { "Data": "report_day", "Type": "string" } ], "MetricColumns": [ { "Data": "visits", "Type": "number" }, { "Data": "pageviews", "Type": "number" }, { "Data": "engaged_page_pageviews", "Type": "number" }, { "Data": "engaged_pageviews_per_visit", "Type": "number" }, { "Data": "engaged_time", "Type": "number" }, { "Data": "bounce_rate", "Type": "number" }, { "Data": "revenue", "Type": "number" }, { "Data": "epmv", "Type": "number" }, { "Data": "copy_paste_per_pageview", "Type": "number" } ], "Segments": [], "Order": { "ColumnNumber": 0, "Direction": "DESC" } } ] }' ``` This returns the custom report's id. If you forget it, list all your custom reports (with ids and names) using `getcustomreports`. Then call `getdata` with the custom report id. You don't need to include dates when the custom report carries a default range: ```bash curl -X POST "https://api-gateway.ezoic.com/bdaservices/getdata/?customReportId=CUSTOM_REPORT_ID&developerKey=YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "StartItem": 0, "MaxItems": 10, "Platform": "ALL", "DomainId": 9999, "DateGrouping": "DAILY" }' ``` ## Segments Segments split data into categories using filters, for example only desktop traffic or only new visitors. List available segments with `getsegments`: ```bash curl -X GET "https://api-gateway.ezoic.com/bdaservices/getsegments/?developerKey=YOUR_API_KEY" ``` This returns both custom segments you created and premade ones, such as "All Users" (no filter) and "Desktop Traffic". To build a segment that filters, say, US and Canada traffic, first find the available filters. There are two filter types: **multifilters** that filter on preset groups (device, country, gender, site) and **filters** that use an operation (greater than, contains, matches exactly, and so on). List multifilters with `getmultifilters`: ```bash curl -X GET "https://api-gateway.ezoic.com/bdaservices/getmultifilters/?developerKey=YOUR_API_KEY" ``` The one we want is the "Country" multifilter: ```json { "FilterName": "Country", "MultiFilterId": 1, "MultiFilterTypeId": 1 } ``` That doesn't tell us the available options. Get those with `getmultifiltertypes`: ```bash curl -X GET "https://api-gateway.ezoic.com/bdaservices/getmultifiltertypes/?developerKey=YOUR_API_KEY" ``` The multifilter type with id `1` maps to the Country filter, and its option keys are two-character country codes. With that, create the segment. Since we aren't using regular filters, we can omit that attribute: ```bash curl -X POST "https://api-gateway.ezoic.com/bdaservices/createsegment/?developerKey=YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "SegmentName": "US and Canada", "SegmentMultiFilters": { "1": { "FilterValues": ["US", "CA"] } } }' ``` You get back a segment object with its `id` filled in. Use that id in a `getdata` request. If the id were `99999`: ```bash curl -X POST "https://api-gateway.ezoic.com/bdaservices/getdata/?customReportId=CUSTOM_REPORT_ID&developerKey=YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "StartItem": 0, "MaxItems": 10, "Platform": "ALL", "DomainId": 9999, "SegmentIds": [99999], "DateGrouping": "DAILY" }' ```