A traffic report gives sellers the ability to review how often their listings appeared on eBay, how many times their listings are viewed, and how many purchases were made. The report also returns the report's start and end dates, and the date the information was last updated.
When using this call:
- Be sure to URL-encode the values you pass in query parameters, as described in URI parameters. See the request samples below for details.
- You can only specify a single metric in the sort parameter and the specified metric must be listed in the metric parameter of your request.
- Parameter names are case sensitive, but metric names are not.
For example, the following are correct:
sort=LISTING_IMPRESSION_TOTAL
sort=lisitng_impression_total
metric=lisitng_impression_total
SORT=LISTING_IMPRESSION_TOTAL
SORT=lisitng_impression_total
Metric=lisitng_impression_total
Input
Resource URI (production)
URI parameters
Parameter | Type | Description |
---|---|---|
dimension | array of string | This query parameter specifies the dimension, or "attribute," that is applied to the report metric. Valid values: DAY or LISTING Examples
Occurrence: Required |
metric | array of string | This query parameter specifies the metrics you want covered in the report. Specify a comma-separated list of the metrics you want included in the report. Valid values:
Occurrence: Required |
filter | array of FilterField | This query parameter refines the information returned in the traffic report. Configure the following properties of the filter parameter to tune the traffic report to your needs:
Example filter parameter The following example shows how to configure the filter parameter with the marketplace_ids and date_range filters:
Note: You must URL encode all the values you supply in the filter parameter, as described in URL parameters. Occurrence: Required |
sort | array of SortField | This query parameter sorts the report on the specified metric. The metric you specify must be included in the configuration of the report's metric parameter. Sorting is helpful when you want to review how a specific metric is performing, such as the CLICK_THROUGH_RATE. Reports can be sorted in ascending or descending order. Precede the value of a descending-order request with a minus sign (" - "), for example: sort=-CLICK_THROUGH_RATE . Occurrence: Optional |
HTTP request headers
OAuth scope
This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):
https://api.ebay.com/oauth/api_scope/sell.analytics.readonly
See OAuth access tokens for more information.
Output
Output container/field | Type | Description |
---|---|---|
dimensionMetadata | array of Metadata | A complex type containing the header of the report and the type of data containted in the rows of the report. Occurrence: Always |
dimensionMetadata.metadataHeader | MetadataHeader | The container that returns the dimensionKeys and metrics headers for the report. Occurrence: Always |
dimensionMetadata.metadataHeader.key | string | The key value used for the report. For example: "key": "LISTING_ID" Occurrence: Always |
dimensionMetadata.metadataHeader.metadataKeys | array of Definition | The list of dimension key values used for the report header. Each list element contains the key name, its data type, and its localized name. For example:
Occurrence: Always |
dimensionMetadata.metadataHeader.metadataKeys.dataType | DataTypeEnum | Indicates the data type of the returned dimension. For example, if the dimension is day , the data type is DATE . Occurrence: Always |
dimensionMetadata.metadataHeader.metadataKeys.key | string | The value the dimension or metric parameter as submitted in the request. Occurrence: Always |
dimensionMetadata.metadataHeader.metadataKeys.localizedName | string | The localized name of the metric or dimension (translated into the language specified in the Accept-Language HTTP request header). For example, if Accept-Language is set to de-DE , the value "day" in the dimension container is returned as "tag", and a metric of TRANSACTION is returned as "Transaktionsanzahl". Occurrence: Always |
dimensionMetadata.metadataRecords | array of MetadataRecord | A list of the individual report records. Occurrence: Always |
dimensionMetadata.metadataRecords.metadataValues | array of Value | A list of data in a row returned in the traffic report. The data in each of the cells match the labels in headers of the report. Occurrence: Always |
dimensionMetadata.metadataRecords.metadataValues.applicable | boolean | If set to true , this flag indicates the value in the value field is valid as computed. A value of false indicates one or more of the values used to calculate the value was invalid. The occurrence of this is a rare, however consider this case: suppose a buyer navigates to a View Item page at 11:59 pm (the end of the day) and purchases the item at 12:05am the next day. In this case, the item would have been purchased with 0 views for the day. Occurrence: Always |
dimensionMetadata.metadataRecords.metadataValues.value | any | The value of the report data. Occurrence: Always |
dimensionMetadata.metadataRecords.value | Value | The value of the key on which the report is based. For example, if the key is the listing ID, the value of this container could be: "value": { Occurrence: Always |
dimensionMetadata.metadataRecords.value.applicable | boolean | If set to true , this flag indicates the value in the value field is valid as computed. A value of false indicates one or more of the values used to calculate the value was invalid. The occurrence of this is a rare, however consider this case: suppose a buyer navigates to a View Item page at 11:59 pm (the end of the day) and purchases the item at 12:05am the next day. In this case, the item would have been purchased with 0 views for the day. Occurrence: Always |
dimensionMetadata.metadataRecords.value.value | any | The value of the report data. Occurrence: Always |
endDate | string | The time stamp is formatted as an ISO 8601 string, which is based on the 24-hour Universal Coordinated Time (UTC) clock. If you specify an end date that is beyond the lastUpdatedDate value, eBay returns a report that contains data only up to the lastUpdateDate date. Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z Example: 2018-08-20T07:09:00.000Z Occurrence: Always |
header | Header | A complex type containing the header for the report. Occurrence: Always |
header.dimensionKeys | array of Definition | A list of the dimension or metric keys returned in the report. The values for each are is returned in the associated key fields. Occurrence: Always |
header.dimensionKeys.dataType | DataTypeEnum | Indicates the data type of the returned dimension. For example, if the dimension is day , the data type is DATE . Occurrence: Always |
header.dimensionKeys.key | string | The value the dimension or metric parameter as submitted in the request. Occurrence: Always |
header.dimensionKeys.localizedName | string | The localized name of the metric or dimension (translated into the language specified in the Accept-Language HTTP request header). For example, if Accept-Language is set to de-DE , the value "day" in the dimension container is returned as "tag", and a metric of TRANSACTION is returned as "Transaktionsanzahl". Occurrence: Always |
header.metrics | array of Definition | The list of metrics returned in the report. The values for each are is returned in the associated key fields. Occurrence: Always |
header.metrics.dataType | DataTypeEnum | Indicates the data type of the returned dimension. For example, if the dimension is day , the data type is DATE . Occurrence: Always |
header.metrics.key | string | The value the dimension or metric parameter as submitted in the request. Occurrence: Always |
header.metrics.localizedName | string | The localized name of the metric or dimension (translated into the language specified in the Accept-Language HTTP request header). For example, if Accept-Language is set to de-DE , the value "day" in the dimension container is returned as "tag", and a metric of TRANSACTION is returned as "Transaktionsanzahl". Occurrence: Always |
lastUpdatedDate | string | The date and time, in ISO 8601 format, that indicates the last time the data returned in the report was updated. Occurrence: Always |
records | array of Record | A complex type containing the individual data records for the traffic report. Occurrence: Always |
records.dimensionValues | array of Value | A list where each element contains either the string DAY (if the dimension is DAY ), or the listing ID for which the record's metric data is computed. A second array member, applicable, is always true for dimension values. Occurrence: Always |
records.dimensionValues.applicable | boolean | If set to true , this flag indicates the value in the value field is valid as computed. A value of false indicates one or more of the values used to calculate the value was invalid. The occurrence of this is a rare, however consider this case: suppose a buyer navigates to a View Item page at 11:59 pm (the end of the day) and purchases the item at 12:05am the next day. In this case, the item would have been purchased with 0 views for the day. Occurrence: Always |
records.dimensionValues.value | any | The value of the report data. Occurrence: Always |
records.metricValues | array of Value | A list where each element contains a value field that indicates the record's value for the metric. Each element also contains an applicable field that indicates the veracity of the computed value. Note that there are no metric names or IDs associated with the values returned in this array. The metadata to which these values relate can be found in the key values Occurrence: Always |
records.metricValues.applicable | boolean | If set to true , this flag indicates the value in the value field is valid as computed. A value of false indicates one or more of the values used to calculate the value was invalid. The occurrence of this is a rare, however consider this case: suppose a buyer navigates to a View Item page at 11:59 pm (the end of the day) and purchases the item at 12:05am the next day. In this case, the item would have been purchased with 0 views for the day. Occurrence: Always |
records.metricValues.value | any | The value of the report data. Occurrence: Always |
startDate | string | The start date of the date range used to calculate the report, in ISO 8601 format. Occurrence: Always |
warnings | array of ErrorDetailV3 | An array of any process errors or warnings that were generated during the processing of the call processing. Occurrence: Conditional |
warnings.category | string | Identifies whether the error was in the REQUEST or happened when running the APPLICATION. Occurrence: Conditional |
warnings.domain | string | The primary system where the error occurred. This is relevant for application errors. For Analytics errors, it always has the value API_ANALYTICS . Occurrence: Conditional |
warnings.errorId | integer | A positive integer that uniquely identifies the specific error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms. Traffic report error IDs range from 50001 to 50500. Occurrence: Conditional |
warnings.inputRefIds | array of string | Identifies specific request elements associated with the error, if any. inputRefId's response is format specific. For JSON, use JSONPath notation. Occurrence: Conditional |
warnings.longMessage | string | A more detailed explanation of the error than given in the message error field. Occurrence: Conditional |
warnings.message | string | Information on how to correct the problem, in the end user's terms and language where applicable. Its value is at most 50 characters long. If applicable, the value is localized in the end user's requested locale. Occurrence: Conditional |
warnings.outputRefIds | array of string | Identifies specific response elements associated with the error, if any. Path format is the same as inputRefId . Occurrence: Conditional |
warnings.parameters | array of ErrorParameterV3 | This optional list of name/value pairs that contain context-specific ErrorParameter objects, with each item in the list being a parameter (or input field name) that caused an error condition. Each ErrorParameter object consists of two fields, a name and a value . Occurrence: Conditional |
warnings.parameters.name | string | Name of the entity that threw the error. Occurrence: Conditional |
warnings.parameters.value | string | A description of the error. Occurrence: Conditional |
warnings.subdomain | string | If present, indicates which subsystem in which the error occurred. Occurrence: Conditional |
HTTP status codes
This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.
Status | Meaning |
---|---|
200 | Success |
400 | Bad Request |
500 | Internal Server Error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
Code | Domain | Category | Meaning |
---|---|---|---|
50001 | API_ANALYTICS | REQUEST | Invalid dimension specified. For help, see the documentation. |
50002 | API_ANALYTICS | REQUEST | Invalid metric {metricName} specified. For help, see the documentation. |
50003 | API_ANALYTICS | REQUEST | Invalid date range. End date must be before or equal to start date. |
50004 | API_ANALYTICS | REQUEST | Invalid date range. Start date must be before or equal to end date. |
50005 | API_ANALYTICS | REQUEST | No filter is specified, which is required. For help, see the documentation. |
50008 | API_ANALYTICS | REQUEST | The call requires at least one metric. For help, see the documentation. |
50009 | API_ANALYTICS | REQUEST | The call requires at least one URI query parameter. For help, see the documentation. |
50013 | API_ANALYTICS | REQUEST | Invalid date range format - Start Date. The format is yyyyMMdd. |
50014 | API_ANALYTICS | REQUEST | Invalid date range format - End Date. The format is yyyyMMdd. |
50018 | API_ANALYTICS | REQUEST | Neither the start date nor the end date can be in the future. |
50021 | API_ANALYTICS | REQUEST | Invalid filter field {filterField} specified. |
50022 | API_ANALYTICS | REQUEST | Specify at least one marketplace ID. |
50023 | API_ANALYTICS | REQUEST | The marketplace ID {marketplaceId} is not supported by this call. For help, see the documentation. |
50024 | API_ANALYTICS | REQUEST | The marketplace ID {marketplaceId} is not valid. |
50025 | API_ANALYTICS | REQUEST | The start date is too far in the past. The start date must be less than or equal to {maxStartDateInThePast}. |
50026 | API_ANALYTICS | REQUEST | The date range is too long. The date range must be less than or equal to {maxDateWindow}. |
50027 | API_ANALYTICS | REQUEST | The 'listing_id' value is empty. |
50028 | API_ANALYTICS | REQUEST | The maximum number of listing IDs has been exceeded. The maximum number of listing IDs is {maxListingIdsNumber}. |
50029 | API_ANALYTICS | REQUEST | Invalid listing ID {listingId}. |
50030 | API_ANALYTICS | REQUEST | Data for the listing ID {listingId} could not be found. |
50031 | API_ANALYTICS | REQUEST | Date range is required. |
50032 | API_ANALYTICS | APPLICATION | We are unable to process data for accounts, like this one, which have listed in more than a few thousand leaf categories in the past couple years. |
50033 | API_ANALYTICS | REQUEST | Invalid date range filter format {invalidDateRangeFilter}. |
50034 | API_ANALYTICS | REQUEST | Invalid listing ids filter format {invalidListingIdsFilter}. |
50035 | API_ANALYTICS | REQUEST | Requested sort field is not part of the list of metrics requested. |
50050 | API_ANALYTICS | APPLICATION | We are doing some maintenance and cannot show all your information right now. We are still tracking everything, and you will see your updated stats soon. |
50500 | API_ANALYTICS | APPLICATION | Internal server error. Wait a few minutes and try the call again. If error persists contact the eBay Developer Program. |
50600 | API_ANALYTICS | REQUEST | Data for the listing Ids {delayedListingIds} is not yet updated to {endDate} |
Warnings
Samples
New to making API calls? Please see Making a Call.
Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.
Sample 1: Generate Traffic Report by Days
Input
Output
Sample 2: Generate Traffic Report by Listing
Input
Output
It also includes the metadata (metadataKeys.key) and metadata records container (metadataRecords). Each of these records contain the metadataRecords.value, which is the listing Id and the (metadataRecords.metadataValues.value), which in this case, the listing title.