Quickstart

This guide will help you get started with the OneWorldSync Python Client.

Basic Setup

First, import the client and initialize it with your credentials:

from oneworldsync import OneWorldSyncClient
import os
from dotenv import load_dotenv

# Load credentials from .env file
load_dotenv()
app_id = os.getenv("ONEWORLDSYNC_APP_ID")
secret_key = os.getenv("ONEWORLDSYNC_SECRET_KEY")

# Initialize client
client = OneWorldSyncClient(app_id, secret_key)

Free Text Search

Perform a simple free text search:

# Search for products containing "milk"
results = client.free_text_search("milk")

# Print number of results
print(f"Found {len(results.products)} products")

# Print details of the first product
if results.products:
    product = results.products[0]
    print(f"Product: {product.brand_name} - {product.product_name}")
    print(f"Description: {product.description}")

Advanced Search

Search for a product by a specific field:

# Search for a product by UPC
results = client.advanced_search("itemIdentifier", "16241419122223")

# Search for products by brand
results = client.advanced_search("brandName", "Organic Valley")

Geo-Location Search

Search for products with geo-location context:

# Search with geo location (San Francisco coordinates)
results = client.free_text_search(
    "coffee",
    geo_location=(37.7749, -122.4194)
)

Working with Search Results

Iterate through search results:

# Iterate through products
for product in results:
    print(f"ID: {product.item_id}")
    print(f"Brand: {product.brand_name}")
    print(f"Name: {product.product_name}")
    print(f"Description: {product.description}")

    # Get product dimensions
    print(f"Dimensions: {product.formatted_dimensions}")

    # Get primary image
    print(f"Primary Image: {product.primary_image_url}")

    # Get all product images
    for image in product.images:
        print(f"Image URL: {image['url']} (Primary: {image['is_primary']})")

Fetching a Specific Product

Get a specific product by ID:

# Get a product by ID
product_data = client.get_product("some_product_id")

# Process the product data
# Note: This returns the raw API response, not a Product object

Converting to Dictionaries

Convert products and search results to dictionaries for easier handling:

# Convert a product to a dictionary
product_dict = product.to_dict()

# Convert entire search results to a dictionary
results_dict = results.to_dict()

# Access metadata
metadata = results_dict['metadata']
print(f"Total results: {metadata['total_results']}")

# Access products
for p in results_dict['products']:
    print(f"{p['brand_name']} - {p['product_name']}")