Obtaining analytics data by using REST API calls

You can obtain analytics data for a specific Catalog and API provider organization by using API Manager REST API calls.

About this task

The REST API calls return JSON objects that contain analytics data. The JSON objects contain the same information as the API event records that you see when you use the API Manager user interface to view the raw data for visualizations.

Procedure

To obtain analytics data for a Catalog and API provider organization, issue the following call: 
GET /v1/orgs/{orgId}/environments/{envId}/events
where
  • {orgId} is either the URL path segment or the ID of the API provider organization.
  • {envId} is either the URL path segment or the ID of the Catalog.
The following table details the query parameters for this call:
Table 1. Query parameters for the analytics REST API call
Parameter Description Default
after The start of the time period for which you want to obtain analytics data. Specify the date/time in UTC format, without a timezone offset; for example, yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.sss. Current time minus 24 hours
before The end of the time period for which you want to obtain analytics data. Specify the date/time in UTC format, without a timezone offset; for example, yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.sss. Current time
fields A list of the event fields that you want included in each event. You can use a comma as a separator when specifying the fields.

Use this parameter if you require only a subset of the event fields rather than the full set.

 Returns all fields by default
limit The number of analytics events that you want to be returned in a single call. If the total number of events is greater than the specified limit, then to obtain the remaining events you issue further calls and supply the next parameter.
Note: The maximum allowed value for the limit parameter is 10000. If this value is exceeded, the API call fails and returns error code 500.
 100
next An ID that is returned on the first call to the API. Supply this ID on subsequent calls to obtain the next set of events. The number of events that is returned in each set of events is determined by the value of the limit parameter. (Not applicable)
[V5.0.8 or later]timeZoneOffset [V5.0.8 or later]From API Connect version 5.0.8.5 onward: The amount of time, in minutes, by which you want the returned datetime and timestamp fields to be adjusted, compared to the original server based values. To add time to the original values, supply a positive value. To subtract time from the original values, supply a negative value. The value must be an integer.
Note: datetime is set by the server, whereas timestamp is set by the analytics engine and is very slightly later.
 [V5.0.8 or later]0

Requests are authenticated using HTTP Basic Authentication. For more information, see Authenticating requests.

Sample calls and responses

The following examples show sample formats for calls that are issued from a browser address bar to obtain analytics data for a Catalog and API provider organization. In the URL, the host address of the API Manager server being queried is specified, and any query parameters are appended with a leading ? and separated with an ampersand (&). A secure login form will prompt for a user name and password for authenticating to the API Manager server. (The API Manager server details are those used for accessing the API Manager UI.)
https://api-manager-server.company.com/v1/orgs/macs-shack/environments/sb/events
https://api-manager-server.company.com/v1/orgs/57cd809ce4b09c68a2183832/environments/57cd80a6e4b09c68a218387b/events
https://api-manager-server.company.com/v1/orgs/smallorg/environments/dev/events?limit=2
https://api-manager-server.company.com/v1/orgs/macs-shack/environments/sb/events?after=2016-08-01T00:00:00.000&before=2016-09-30T23:59:59.999
The following examples show sample formats for calls that are issued as curl commands to obtain analytics data for a Catalog and API provider organization. In the commands, the Internet protocol string specifies the host address of the API Manager server being queried, and any query parameters are appended with a leading ? and separated with an ampersand (&). The -u option specifies only the user name, rather than the user name and password combination (user_name:password), to prevent the password from being shown in plain text.
[Icon indicating that this applies on Linux platforms]
curl -k -X GET -u 'username@company.com' 'https://api-manager-server.company.com/v1/orgs/macs-shack/
environments/sb/events?after=2016-08-01T00:00:00.000&before=2016-09-30T23:59:59.999'
[Icon indicating that this applies on Windows platforms]
curl -k -X GET -u "username@company.com" "https://api-manager-server.company.com/v1/orgs/macs-shack/
environments/sb/events?after=2016-08-01T00:00:00.000&before=2016-09-30T23:59:59.999&limit=2"
[V5.0.7 or later]
Restriction: The billing object fields are only supported in Version 5.0.7.2, and later.
The following example shows a call that is issued from a browser and then shows all the event fields in the corresponding response. The call is issued to return two analytics events (limit=2), and includes a next parameter for requesting further events.
https://api-manager-server.company.com/v1/orgs/macs-shack/environments/sb/events?next&limit=2
{
  "totalCalls": 5,
  "next": "5792250fe4b0838bc6abfc0a",
  "nextHref": "https://api-manager-server.company.com/v1/orgs/macs-shack/environments/sb/events?next=5792250fe4b0838bc6abfc0a",
  "calls": [
    {
      "datetime": "2016-07-22T13:51:08.658Z",
      "timestamp": "2016-07-22T13:51:08.748Z",
      "apiName": "fins",
      "apiVersion": "1.0.0",
      "appName": "Surfboards",
      "catalogName": "sb",
      "planName": "default",
      "planVersion": "1.0.0",
      "productName": "surfing-products",
      "productVersion": "1.0.0",
      "devOrgName": "bluebottle-boards",
      "resourceName": "/stocklist",
      "timeToServeRequest": 243,
      "bytesSent": 115,
      "requestProtocol": "https",
      "requestMethod": "GET",
      "uriPath": "/macs-shack/sb/surf/stocklist",
      "queryString": "",
      "statusCode": "200 OK",
      "requestHeaders": "",
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.106 Safari/537.36",
      "requestBody": "",
      "responseHeaders": "",
      "responseBody": "",
      "latency": "Initialization=0ms : Start=8ms : PlanRateLimits=4ms : Plan Limit=2ms : Finservice=221ms : PlanRateLimits=8ms",
      "rateLimit": {
        "per-minute": {
          "limit": "100",
          "count": "5",
          "period": "60",
          "reject": "false",
          "shared": "true"
        }
      },
      "logPolicy": "activity",
      "orgName": "macs-shack",
      "resourcePath": "get",
      "productTitle": "Surfing Products",
      "clientGeoIp": {
        "ip": "9.20.152.215",
        "country_code2": "US",
        "country_code3": "USA",
        "country_name": "United States",
        "continent_code": "NA",
        "region_name": "NC",
        "city_name": "Durham",
        "postal_code": "27709",
        "latitude": 35.994,
        "longitude": -78.8986,
        "dma_code": 560,
        "area_code": 919,
        "timezone": "America/New_York",
        "real_region_name": "North Carolina",
        "location": [
          -78.8986,
          35.994
        ]
      },
      "billing": {
        "trial_period_days": "0",
        "amount": "0",
        "currency": "USD",
        "model": "free",
        "provider": "none"  
      }
      "gatewayGeoIp": {
        "ip": "9.20.98.109",
        "country_code2": "US",
        "country_code3": "USA",
        "country_name": "United States",
        "continent_code": "NA",
        "region_name": "NC",
        "city_name": "Durham",
        "postal_code": "27709",
        "latitude": 35.994,
        "longitude": -78.8986,
        "dma_code": 560,
        "area_code": 919,
        "timezone": "America/New_York",
        "real_region_name": "North Carolina",
        "location": [
          -78.8986,
          35.994
        ]
      }
    },
    {
      "datetime": "2016-07-22T13:51:07.375Z",
      "timestamp": "2016-07-22T13:51:08.465Z",
      "apiName": "fins",
      "apiVersion": "1.0.0",
      "appName": "Surfboards",
      "catalogName": "sb",
      "planName": "default",
      "planVersion": "1.0.0",
      "productName": "surfing-products",
      "productVersion": "1.0.0",
      "devOrgName": "bluebottle-boards",
      "resourceName": "/stocklist",
      "timeToServeRequest": 248,
      "bytesSent": 115,
      "requestProtocol": "https",
      "requestMethod": "GET",
      "uriPath": "/macs-shack/sb/surf/stocklist",
      "queryString": "",
      "statusCode": "200 OK",
      "requestHeaders": "",
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.106 Safari/537.36",
      "requestBody": "",
      "responseHeaders": "",
      "responseBody": "",
      "latency": "Initialization=0ms : Start=10ms : PlanRateLimits=4ms : Plan Limit=2ms : Finservice=225ms : PlanRateLimits=7ms",
      "rateLimit": {
        "per-minute": {
          "limit": "100",
          "count": "4",
          "period": "60",
          "reject": "false",
          "shared": "true"
        }
      },
      "logPolicy": "activity",
      "orgName": "macs-shack",
      "resourcePath": "get",
      "productTitle": "Surfing Products",
      "clientGeoIp": {
        "ip": "9.20.152.215",
        "country_code2": "US",
        "country_code3": "USA",
        "country_name": "United States",
        "continent_code": "NA",
        "region_name": "NC",
        "city_name": "Durham",
        "postal_code": "27709",
        "latitude": 35.994,
        "longitude": -78.8986,
        "dma_code": 560,
        "area_code": 919,
        "timezone": "America/New_York",
        "real_region_name": "North Carolina",
        "location": [
          -78.8986,
          35.994
        ]
      },
      "gatewayGeoIp": {
        "ip": "9.20.98.109",
        "country_code2": "US",
        "country_code3": "USA",
        "country_name": "United States",
        "continent_code": "NA",
        "region_name": "NC",
        "city_name": "Durham",
        "postal_code": "27709",
        "latitude": 35.994,
        "longitude": -78.8986,
        "dma_code": 560,
        "area_code": 919,
        "timezone": "America/New_York",
        "real_region_name": "North Carolina",
        "location": [
          -78.8986,
          35.994
        ]
      }
    }
  ]
}