Introduction

Zitcha's Search API enables networks to seamlessly integrate sponsored products and display ads into their websites and applications. The API provides two endpoints:

1. /v1/search/products: This endpoint retrieves sponsored products, offering both detailed (verbose) and simplified responses based on your needs. The detailed responses include comprehensive product information such as title, price, image URL, and description, making it easy to render products directly from the API response. Simplified responses return a list of SKUs and Ad-IDs, allowing you to fetch additional product details from your internal systems.
2. /v1/search/banners: This endpoint retrieves display ads, providing required data to render ads including URL, image links, and creative dimensions.

Both endpoints support advanced filtering and pagination, allowing for fine-grain control over the search results. This flexibility ensures that you can tailor the integration to meet specific requirements, optimise performance, and enhance user experience.

Key Decisions for Implementation

When implementing the Zitcha Search API into your applications, the flexibility of our response structure allows you to optimise the implementation to best suite your existing logic for retrieving and filtering products. There are 2 key decisions to make as well as optional pagination:

1. Response Verbosity
   • Verbose Responses:
     • Use Case: When you prefer to render sponsored products directly using the information provided by the API.
     • Implementation: Configure your API requests to specify verbose responses. This includes all product details such as image URL, title, price, description, and more.
     • Considerations: This option may reduce the API calls required to render a sponsored product on your network.
   • Simplified Responses:
     • Use Case: When you prefer to fetch detailed product information from your internal systems.
     • Implementation: Configure your API requests to specify simplified responses. This only returns a list of SKUs and Ad-ID’s, and you will need to make additional requests to your internal systems to get detailed product information.
     • Considerations: This reduces the response size and depending on your implementation may ease in the process of rendering products as you can use your existing data structure to do so.
2. Filtering Strategy
   • Server-Side Filtering via API:
     • Use Case: When you want to leverage Zitcha’s filtering capabilities to ensure accurate and up-to-date results.
     • Implementation: Include filter parameters in your API requests to retrieve a filtered set of promoted products or display ads. Filters can be based on various fields such as brand, sale, and any custom attributes supplied in your product feed.
     • Considerations: This approach ensures the filtering logic is consistent and leverages Zitcha’s search capabilities, but it requires making multiple API requests if additional filters are applied based on user interactions.
   • Client-Side Filtering:
     • Use Case: When you prefer to handle filtering logic on your end.
     • Implementation: Fetch an initial set of promoted SKUs from the Zitcha search API and then apply additional filters on your backend based on user interactions.
     • Considerations: This reduces the number of API calls but requires your backend to handle the filtering logic and ensure data consistency. This is often the preferred option as filtering can be handled across the entire promoted and organic set of products.
3. Optional Pagination
   • Purpose: Handle large sets of results efficiently by implementing pagination.
   • Implementation:
     • Use the page and per_page parameters in your API requests to control the number of results returned per page and navigate through multiple pages of results.
     • Implement logic in your application to handle pagination, including fetching subsequent pages of results as needed and displaying pagination controls in the UI.
     • Useful when requesting sponsored products over many pages in a single search. e.g. requesting sponsored products for subsequent listing of 24 products

Steps for Implementing the Search API

1. Configure API Integration
   • Obtain API Credentials: Ensure you have the necessary API credentials from Zitcha to authenticate your requests.
   • Set Up API Endpoints: Configure the endpoints to send requests to https://api.zitcha.app/search.
2. Decide on Response Verbosity
   • Verbose Response: Use when you need detailed product information directly from the API.
   • Simplified Response: Use when you prefer to fetch detailed product information from your internal systems using the returned SKUs.
3. Implement Filtering Strategy
   • Server-Side Filtering: Use Zitcha’s filtering capabilities by including filter parameters in your API requests.
   • Client-Side Filtering: Fetch an initial set of SKUs and apply additional filters on your backend based on user interactions.
4. Share product feed
   • API or Batch: Use Zitcha’s Collect API or a batch processing method to share your product feed and updates. This enables advertisers to view and buy sponsored products.
   • Schema: Depending on your desired response structure and filtering requirements you will need to provide an appropriate product schema. For example if you would like to filter by custom values you will need to provide these in your schema.
5. Optionally Handle Pagination
   • Request Parameters: Use the page and per_page parameters in your API requests to manage pagination.
   • Backend Logic: Implement backend logic to handle pagination, fetch subsequent pages of results, and manage pagination controls in the UI.

Example Workflow

1. User Navigates to a Category Page:
   • The network’s backend makes a request to the Zitcha search API to get promoted SKUs relevant to the category.
   • Depending on the verbosity setting, either detailed product information or a list of SKUs is returned.
2. Rendering Products:
   • Verbose: Use the detailed information directly to render the products.
   • Simplified: Fetch additional product details from internal systems using the SKUs.
3. User Applies a Filter (e.g., Prescription Medicine):
   • Server-Side Filtering: Make another request to the Zitcha search API with the applied filter to get updated promoted SKUs.
   • Client-Side Filtering: Filter the list of promoted products on the backend using the user’s filter criteria.
4. User Interacts with Ad
   • Register Impression/Click: Once the ad is rendered and viewed in a users viewport, the impressions needs to be registered with Zitcha via the Collect API to ensure up to date and accurate reporting and ad optimisation.

Conclusion

By following this implementation guide, you can effectively integrate the Zitcha Search API into your network, ensuring flexibility in response verbosity and filtering strategy. This allows for a tailored integration that meets your specific requirements, optimising the delivery and display of sponsored products and display ads.

If you need further assistance or more detailed information, please refer to the API documentation or contact Zitcha's support team.