Contact support
    • Monetization
    • Developer documentation
    • Onboard data
    • Onboard contextual data
    • EIQI API integration

    EIQI API integration: URL/bundle categorization

    Table of Contents

    Overview Provider endpoint requirements Provider responses – HTTP response codes HTTP 200 response payload format

    Overview

    The process of URL/bundle categorization by contextual data providers involves the following steps:

    • The data provider makes available an endpoint to which Equativ can send categorization request.
    • In a categorization request, Equativ sends a URL/bundle to the provider’s endpoint.
    • The provider returns the corresponding segment IDs for the URLs/bundles sent in the categorization request.

    Provider endpoint requirements

    The endpoint the data provider makes available to Equativ for categorization requests must comply with the following requirements:

    • must support GET request sent by Equativ
    • must be accessible behind an HTTP basic authentication, a simple authentication scheme that is built into the HTTP protocol: the client sends HTTP requests with the Authorization header that contains the Basic word, followed by a space and a base64-encoded username:password string. For instance, a header containing the username demo and the password p@55w0rd credentials would be encoded as: Authorization: Basic ZGVtbzpwQDU1dzByZA==
    • must follow this format:
      • For URLs: https://<ProviderEndpoint>?url=<URLToCategorize>
      • For Bundles: https://<ProviderEndpoint>?store=<BundleStore>&bundle=<BundleIdToCategorize>
    • must support bundle stores (apple, android, etc.). Bundle stores are the specific platforms or environments where bundles are available for use. Available bundle stores (case-sensitive):
      • amazon
      • android
      • apple
      • Ig
      • microsoft
      • philips
      • roku
      • samsung
      • sony_playstation
      • vizio

    Provider responses – HTTP response codes

    When Equativ requests the categorization of a URL/bundle, the data provider must adapt its response, depending on the status of the URL/bundle.

    The table below summarizes the rules applied when Equativ calls the data provider’s endpoint, including:

    • the HTTP status code the data provider must return
    • the payload the data provider must return
    • the resulting behavior on Equativ’s side.
    Status HTTP status code Payload Resulting behavioron Equativ’s side
    The URL/bundle has already been categorized HTTP 200 The list of segments(see “HTTP 200 response payload format” below) Equativ ingests the segments associated with the URL/bundle.Segments in the payload that have not been synchronized with Equativ (see EIQI API integration: upload taxonomy) are considered as unknown and therefore ignored.
    The URL/Bundle has already been categorized but the data provider does not associate it with any segment - orthe data provider does not want this URL/bundle to be requested again - orthe URL/bundle cannot be categorized HTTP 204 No payload Equativ will stop requesting this URL/bundle for 48 hours.
    The URL/bundle has not yet been categorized HTTP 202 No payload After receiving an HTTP 202 response for the first time, Equativ will request the same URL/bundle 3 more times, every <X> minutes, depending on the provider. The value <X> is configurable and is established during the initial setup, upon the provider's request.In case each attempt returns an HTTP 202 response, Equativ will stop requesting this URL/Bundle for the cache duration specified during the provider integration.

    HTTP 200 response payload format

    A HTTP 200 response with the payload indicates a successful request. The payload contains a simple list of case-sensitive segments, previously uploaded using the taxonomy API (see EIQI API integration: upload taxonomy).

    Example HTTP 200 response with payload

    {
            "segments": [
                       "my-segment-id-1",
                       "my-segment-id-2",
                       "my-segment-id-3",
                       "..."
            ]
}

    Note that the list of segments must not be empty.

    If you require any customizations of your API integration, contact your account manager to schedule a call with our dedicated technical team.

    RELATED ARTICLES