Okube Analytics API Documentation (1.45.11)

The Okube API uses standard HTTP status codes to indicate the success or failure of requests. This consistent approach allows for straightforward error handling in your applications.

• 2xx Success: Request was received, understood, and processed successfully.
• 4xx Client Errors: Request contains invalid syntax or cannot be fulfilled due to client-side issues.
• 5xx Server Errors: Server failed to fulfill a valid request due to internal issues.

Success Responses

• 200 OK: Request succeeded. Response contains requested data.
• 201 Created: Resource was successfully created.
• 204 No Content: Request succeeded, but no content is returned.

Client Error Responses

• 400 Bad Request: The request contains invalid parameters or malformed syntax.
• 401 Unauthorized: Authentication credentials are missing or invalid.
• 403 Forbidden: Authentication succeeded, but the authenticated user lacks permission.
• 404 Not Found: The requested resource does not exist.
• 422 Unprocessable Entity: Request is well-formed but contains semantic errors.
• 429 Too Many Requests: You've exceeded the rate limit for API calls.

Server Error Responses

• 500 Internal Server Error: An unexpected error occurred on the server.
• 503 Service Unavailable: Server is temporarily unavailable, typically due to maintenance.

All error responses include a JSON body with detailed information to help diagnose the issue.

The Okube API implements efficient pagination for all list endpoints that return collections of resources (e.g., applications, sites, campaigns). This approach optimizes performance and response times when working with large datasets.

Request Parameters

All paginated endpoints require the following query parameters:

• page: Integer specifying the page number (starting from 1)
• per_page: Integer specifying the number of items per page (typically 10-100)

Response Format

Paginated responses consist of two primary components:

1. documents: An array containing the requested resources for the current page
2. _$paginated: Metadata object with the following properties:
   • total: Total number of resources matching the query
   • page: Current page number
   • per_page: Number of items per page
   • page_count: Total number of pages available
   • has_more: Boolean indicating whether additional pages exist

Example Usage

GET /applications?page=2&per_page=25

This request will return the second page of applications, with 25 items per page.

CSV Export Option

Many list endpoints support an additional accept: text/csv header to download results in CSV format, bypassing pagination for complete data export.

For detailed schema information, see the PaginatedResponse schemas section.

The Okube API organizes resources hierarchically, with most endpoints scoped under either an Application (client account) or a Site (physical location or digital property). This structure is reflected in the URL patterns used throughout the API.

The API supports multiple ways to identify resources:

• Using unique MongoDB identifiers (UUID format)
• Using human-readable keys (URL-friendly slugs)

Applications serve as top-level containers for most resources and can be referenced in two ways:

• /applications/{id}: Using the application's unique identifier
• /applications/{key}: Using the application's unique key

Sites represent business locations or digital properties and can be accessed through several URL patterns:

• Direct access: /sites/{id}
• Within application context:
  • /applications/{id}/sites/{id}
  • /applications/{id}/sites/{key}
  • /applications/{key}/sites/{id}
  • /applications/{key}/sites/{key}

• When creating integrations, prefer using stable keys rather than IDs when possible
• For performance-critical operations, direct ID-based routes typically offer better performance
• For exploratory API use, key-based routes provide better readability and debuggability

The Okube API secures all requests using JSON Web Tokens (JWT). Two authentication methods are available:

1. Revocable API Keys: Ideal for long-term integrations and automated systems.
2. 48-hour Access Tokens: Short-lived tokens suitable for user sessions and temporary access.

Security Notice: JSON Web Tokens grant access privileges to your data. Always store them securely and never expose them in client-side code, public repositories, or insecure communications channels.

To obtain a 48-hour access token, submit your credentials to the Authentication Endpoint.

Authentication Header Example:

-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Important Requirements:

• All API requests must use HTTPS protocol. Unencrypted HTTP requests will be rejected.
• Unauthenticated requests will receive a 401 Unauthorized response.

The Analytics endpoints utilize a structured query language that leverages both query parameters and request body for comprehensive configuration.

Query parameters are used to:

• Define the data period with from and to parameters.
• Enable or disable specific features, such as uplift analysis.

The request body accepts only application/json content and allows configuration through:

• Optional filters to refine data selection.
• Mandatory params to specify analytical operations.

Detailed specifications for filters and params can be found in each module's documentation.

Filters

Filters allow you to select data based on specific scope values. These filters are applied globally across all queries within the request (refer to params for additional details).

Params

The params section defines the core of an analytics query. Each parameter specifies:

• The kpi (Key Performance Indicator) to analyze.
• The statistical mode, which can be either:
  • histogram for time-series analysis
  • aggregation for consolidated metrics
• The time granularity, which can be:
  • day for daily analysis
  • week for weekly analysis
  • month for monthly analysis
  • year for yearly analysis

For each kpi query, projections can be configured for specific scopes as follows:

• all: When set to false, excludes aggregated data by scope.
• temporals: When set to false, excludes data aggregated by both scope and granularity.

Projections for specific scopes are determined based on the data module:

• Global Scopes:
  • globals: When set to false, excludes data aggregated by no-scope.
• Application-Specific Scopes:
  • sites: When set to true, includes data aggregated by site (available in all application queries).
• Conversion Module Scopes:
  • campaigns for campaign-level metrics
  • levers for marketing lever analysis
• GeoMarketing Module Scopes:
  • homes (IRIS statistical areas)
  • works (IRIS statistical areas)
  • (depreacted) zones (IRIS statistical areas)
• Presence Module Scopes:
  • equipments for device-level analysis

Additionally, for certain scopes, you can specify which property (key, name, etc.) should be projected alongside the data. Detailed information is available in the respective schema documentation.

The API response is an array, where each element includes:

• kpi: The Key Performance Indicator that was analyzed
• scope: The scope level of the analysis
• granularity: The time granularity used
• data: The resulting dataset

Data Organization

The data object contains query results organized by scope and granularity:

• Global Scope:
  • all: Contains metrics aggregated across the entire time period.
  • temporals: Contains metrics organized by time granularity.
• Other Scopes:
  • Each scope-specific object includes both all and temporals sections.

Temporal Data Behavior

The structure of temporals data depends on the selected mode:

• histogram Mode:
  • Keys represent sequential time increments (e.g., day, week, month, year).
  • Example: For granularity: day and from: 2023-01-02, key 0 corresponds to 2023-01-02, key 1 to 2023-01-03, and so on.
• aggregation Mode:
  • Keys represent categorical time periods (e.g., day of week, month of year).
  • Example: For granularity: day, key 1 aggregates all Mondays, key 2 aggregates all Tuesdays, within the specified time period.

Module KPIs

Available Scopes

The GeoMarketing module provides location-based analytics across:

• homes: Residential areas defined by geographical regions (IRIS statistical divisions)
• works: Workplace locations defined by geographical regions (IRIS statistical divisions)

Application-Related Scopes

The module also provides insights across:

• sites: Retail and business locations

For additional information about query structure, parameters, and response formats, please refer to the Analytics documentation.

Module KPIs

Available Scopes

The Conversion module provides analytics across the following scopes:

• levers: Marketing channels and mechanisms
• campaigns: Marketing campaigns and initiatives
• extras: Campaign attributes in Key:Value format

Application-Related Scopes

The module also provides insights across:

• sites: Retail and business locations

For additional information about query structure, parameters, and response formats, please refer to the Analytics documentation.

Module KPIs

Available Scopes

The Presence module provides customer flow analytics across:

• Device-Level Scopes:
  • equipments: Connected devices and tracking systems

Multi-Level Insights

The module supports hierarchical analysis through:

• Application-Level Scopes:
  • sites: Retail and business locations
• Site-Level Scopes:
  • equipments: Connected devices within specific locations

For additional information about query structure, parameters, and response formats, please refer to the Analytics documentation.

Sites represent physical locations or digital properties managed within the Okube Analytics platform. The Site endpoints provide comprehensive functionality for creating, retrieving, updating, and listing all sites associated with your applications.

Key Features

• Site Creation: Register new physical locations or online properties with detailed attributes
• Site Retrieval: Access comprehensive information about specific sites
• Site Updates: Modify site details, geographical data, and operational parameters
• Site Listing: Browse all sites with powerful filtering and pagination options
• Bulk CSV Import: Efficiently import multiple sites via CSV upload

Site Types

The API supports two distinct site types:

• Offline Sites: Physical locations with geographical coordinates and address information
• Online Sites: Digital properties without physical location data

Site Properties

Sites include essential attributes such as:

• Identifying information (name, key, reference codes)
• Location data (coordinates, address) for offline sites
• Operational details (opening hours, capacity)
• Categorization (tags, type)
• Custom attributes for specialized analysis

Resource Relationships

Sites are linked to:

• Applications: The client account that owns the site
• Campaigns: Marketing initiatives targeting the site
• Equipment: Tracking devices installed at the site

Analytics Integration

Sites serve as fundamental organizational units for:

• Geo-marketing analysis
• Conversion tracking
• Customer presence monitoring
• Multi-site performance comparison

Points of Interest (POIs) represent specific geographical locations that are relevant for geo-marketing analysis. The POI endpoints allow you to create, retrieve, update, and list locations that are important for your business analysis.

Key Features

• POI Creation: Register new geographical points with precise coordinates and classification
• POI Retrieval: Access detailed information about specific locations
• POI Updates: Modify location details, categorization, and associated properties
• POI Listing: Browse all points of interest with filtering and pagination options
• Geographical Filtering: Search POIs by proximity, region, or relation to other elements

POI Properties

Points of Interest include essential attributes such as:

• Geographical coordinates (latitude/longitude)
• Descriptive information (name, description)
• Categorization (type, tags)
• Custom attributes for specialized analysis

Resource Relationships

Points of Interest can be linked to:

• Applications: The client account that manages the POI
• Sites: Physical locations related to the POI
• Geo-Marketing Studies: Analysis projects incorporating the POI data

Analytical Applications

POIs serve as crucial reference points for:

• Catchment area analysis
• Competition mapping
• Footfall correlation studies
• Site potential evaluation