Welcome to the GSIQ API

The GSIQ API provides access to our comprehensive dataset of sports marketing insights, allowing users to retrieve filtered media, sponsorship, and engagement data. Whether you're analysing sponsorship impact, media exposure, or engagement metrics, the API enables streamlined access to key performance indicators.

Getting Started

To use the GSIQ API, you need an API key. You can obtain this key by logging into the GSIQ Dashboard and generating your unique API key in the settings panel.

You will only be able to do this if API access has been enabled on your account by our support team in advance. Please contact support on the link below for more details.

The API key acts as your authentication credential and should be included in all requests. API keys must be kept secure and should not be shared.

Authentication

All API requests must include your API key in the request header:

        X-Api-Key: YOUR_API_KEY
    

Without a valid API key, requests will be denied with a 401 Unauthorised error. If you believe your key has been compromised, you can regenerate a new key in the client dashboard.

Rate Limits

To ensure fair usage and system stability, the GSIQ API enforces rate limits. The current rate limits are as follows:

• 200 requests per hour

If you exceed the rate limit, the API will return a 429 Too Many Requests response. If you require a higher limit, please contact GSIQ Support to discuss upgrade options.

Best Practices to Avoid Rate Limit Issues

• Use caching for frequently accessed data to reduce API calls.
• Batch requests where possible to minimise individual calls.
• Implement retry logic with exponential backoff in case of rate limit errors.
• Monitor API usage and optimise queries to stay within limits.

How to Use the API

You can interact with the API using various tools, including:

• cURL: A command-line tool for making API requests.
• Postman: A graphical interface for testing API endpoints.
• Programming Languages: You can integrate the API into applications using Python, JavaScript, or any language that supports HTTP requests.
• API Clients: Various open-source API clients such as Insomnia or Swagger UI can be used to explore endpoints.

Querying Data

To retrieve meaningful data, follow these steps:

1. First, set up your filters by retrieving the available filter options using endpoints like:
• /api/v1/filter/events - Get available events
• /api/v1/filter/assets - Get available assets
• /api/v1/filter/sponsors - Get sponsor information
• /api/v1/filter/countries - Get countries (media geography)
• /api/v1/filter/teams - Retrieve team information
• /api/v1/filter/participants - Get participants (players)
• /api/v1/filter/channeltypes / programmetypes - Channel and programme types
• /api/v1/detail/mediatypes, segments, kpis - Detail grouping options
2. Use the filter values to refine your query based on the criteria relevant to your analysis.
3. Call the /api/v1/filter/filter endpoint to set up filtering criteria.
4. Once the filters are configured, use the /api/v1/detail/data endpoint to fetch aggregated media metrics (Sponsor Value, AVE, Brand Exposure, etc.).

Example API Call

Here’s an example of how to retrieve media data using cURL (Broadcast, grouped by Sponsor, focused on Sponsor Value):

    curl -X GET "https://api.gsiq.biz/api/v1/detail/data?mediaTypeIds=1&segmentId=13&kpiId=6&filterIndex=1" \
    -H "X-Api-Key: YOUR_API_KEY"

You can refine results further by setting event, country, sponsor, and other IDs on the filter before calling detail data.

Understanding the Response

All API responses are returned in JSON format. A successful request will return an array of data in this structure:

    [{
        "mediaTypeId": 1,
        "mediaType": "Broadcast",
        "segmentId1": 13,
        "segmentValueId1": 1,
        "segmentName1": "Acme Bank",
        "dataCount": 2869,
        "audience": 500000,
        "brandExposure": 12.5,
        "ave": 10108507,
        "sponsorValue": 4892522
        ...
    },
    ...
    ]

Each field represents key valuation and exposure metrics aligned with the GSIQ Client Detail view (audience, brand exposure, Sponsor Value, AVE, SIQ+, and related KPIs).

Error Handling

If your request encounters an error, the API will return a structured response indicating the issue:

    {
        "message": "Invalid request parameters",
        "statusCode": 400
    }

Common errors include:

• 400 Bad Request - Invalid query parameters or missing required fields.
• 401 Unauthorised - Missing or invalid API key.
• 403 Forbidden - You do not have permission to access this resource.
• 404 Not Found - Requested resource does not exist.
• 429 Too Many Requests - Rate limit exceeded.

Need Help?

For additional assistance, contact GSIQ Support. Our team is available to help with authentication, query optimisation, and data interpretation. You can also visit our API Documentation for detailed endpoint descriptions and usage examples.