Guides

Get Offers

Suggest Edits

The Get Offers API endpoint provides a way to retrieve a comprehensive list of available offers. Its primary purpose is to allow an application to display a browsable catalog of deals to the user. The endpoint is highly flexible, supporting advanced filtering by location, category, and tags, as well as robust sorting and pagination options to create a customized user experience.

Prerequisites

Before making an API call to get offers, ensure that the necessary user-level session token has been obtained. This token is required to authenticate API requests and can be acquired by following the User Client Level Authentication.

Steps to Implement

  1. Construct the API Request

    • Purpose: Allows a client to retrieve a set of tailored offers.
    • Endpoint Reference: Get offers
    • Usage: Make a GET request to the specified endpoint. The results can be tailored by appending various query parameters to the URL. For instance, you can add parameters for location (latitude, longitude), filtering (filter), sorting (sort_by), and pagination (limit, offset).

  2. Process the Response

    • Purpose: To handle the data returned by the API and display it within the application.
    • Response Body: A successful (200 OK) response will contain a JSON object with a list of offers that match the query criteria.
    • Error Handling: Your application should be prepared to handle potential error responses, such as 400 Bad Request if query parameters are invalid, or 500 Internal Server Error if the service fails to process the request. The error response body will contain an error_code and a user-friendly error_message.

Key Considerations

  1. Pagination is Essential: Always use the limit and offset parameters to manage the number of returned results. Fetching an unbounded list of offers can lead to poor performance and long loading times. A typical implementation would fetch a set number of offers (e.g., 20) and use the offset to load more as the user scrolls.
  2. Location-Based Searching: To search for offers within a specific geographic area, you must provide the latitude, longitude, and radius parameters together. Omitting any of these will result in the location filter failing.
  3. Complex Filtering: The filter parameter is a powerful JSON object that allows for deep filtering based on multiple criteria. Ensure that the object structure is correctly formatted to avoid 400 Bad Request errors.
  4. Sorting Options: The sort_by parameter allows results to be ordered by relevance, distance, or popularity. This can be used to surface the most relevant offers to the user first.

Example Workflow

Scenario: A user wants to find the most popular dining offers within a 10-kilometer radius of their current location.

  1. Get User Location: The application first obtains the user's current latitude and longitude from their device.
  2. Construct Request: The application builds and sends a GET request to the Kigo API.
    1. Endpoint: Get offers
    2. Query Parameters
      1. latitude=44.9441
      2. longitude=-93.0936
      3. radius=10
      4. search_radius_unit=kilometers
      5. filter={"category": "dining"}
      6. sort_by=[{"field": "most_popular_brands"}]
      7. limit=25
      8. offset=0
  3. Receive Response: The Kigo API returns a 200 OK status and a JSON response containing a list of up to 25 of the most popular dining offers matching the criteria.
  4. Display Results: The application parses the JSON response and displays the list of offers, including details like the merchant name, offer title, and savings.
  5. Load More: If the user scrolls to the end of the list, the application can make a new API call with an increased offset (e.g., offset=25) to fetch the next page of results.

Best Practices

  • Implement Sensible Defaults: For a better user experience, set default values for parameters like limit and search_radius in your application.
  • Validate User Input: Before making an API call, validate any user-provided input, such as coordinates, to ensure it is in a valid format.
  • Use Specific Filters: Leverage the filter parameter to narrow down results on the server-side. Avoid fetching a large, unfiltered dataset and performing the filtering on the client, as this is inefficient.
  • Cache Strategically: For general, non-personalized requests that are likely to be repeated, consider caching the results for a short duration to improve your application's responsiveness and reduce the number of API calls.

Updated 3 days ago