Developer Guide: Using the Taxonomy Matcher Public API

This guide is for developers looking to integrate the Taxonomy Matcher's capabilities into their own applications or workflows programmatically.

1. Introduction to the Public API

The Public API allows you to:

• Submit product data for categorization.
• Use either the default Google Product Taxonomy or provide your own custom taxonomy string in the request.
• Receive matched category paths for your products.

All API usage is tied to your account's credit balance.

2. Generating and Managing Your API Keys

Before you can use the API, you need to generate an API key.

a. Accessing API Key Management:

1. Log in to your Taxonomy Matcher account.
2. Navigate to your Dashboard.
3. Click on the "API Key Management" section (or a similarly named link).

b. Creating a New API Key:

1. On the "Manage API Keys" page, find the "Create New API Key" form.
2. Enter a descriptive Name for your key (e.g., "My E-commerce Integration Key", "Data Processing Script Key").
3. Click "Create Key".

c. Storing Your API Key Securely:

• Upon creation, your full API key will be displayed ONCE.
• Copy this key immediately and store it in a secure location (like a password manager or a secure environment variable for your application).
• You will not be able to see the full key again. You will only see its prefix for identification purposes.
• Treat your API key like a password. Do not share it publicly or commit it to version control.

d. Viewing and Deleting API Keys:

• The "Manage API Keys" page lists all your keys, showing their name, prefix, creation date, and last used date.
• You can delete (revoke) an API key if it's compromised or no longer needed. This action is permanent.

3. Authenticating Your API Requests

All requests to the Public API must include your API key in the X-API-Key HTTP header.

X-API-Key: your_full_api_key_here

If the API key is missing, invalid, or revoked, the API will return a 401 Unauthorized error.

4. Making a Matching Request

The primary endpoint for matching is:

• URL: /api/public/match
• Method: POST
• Headers:
  • Content-Type: application/json
  • X-API-Key: YOUR_API_KEY
• Request Body: A JSON object containing products and an optional taxonomy string.

a. Request Body Structure:

{
  "products": [
    {
      "id": "YOUR_PRODUCT_ID_1",
      "title": "Product Title 1",
      "description": "Detailed description for product 1."
    },
    {
      "id": "YOUR_PRODUCT_ID_2",
      "title": "Product Title 2",
      "description": "Detailed description for product 2."
    }
    // ... up to 100 products
  ],
  "taxonomy": "Optional custom taxonomy string (see format below)"
}

• products (array, required):
  • Each object needs id (string), title (string), description (string).
  • Max 100 products per request.
• taxonomy (string, optional):
  • If provided, this string will be used as the custom taxonomy.
  • Format: Newline-separated category paths, with > as the hierarchy delimiter. Example: "Electronics > Audio\nElectronics > Video"
  • If omitted or empty, the default Google Product Taxonomy is used.

b. Example Request (cURL):

curl -X POST 'https://your-app-domain.com/api/public/match' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: sk_yourGeneratedApiKeyHere_xxxxxxxx' \
-d '{
  "products": [
    {
      "id": "SKU001",
      "title": "Premium Wireless Headphones",
      "description": "Experience immersive sound with these noise-cancelling wireless headphones. Features Bluetooth 5.0 and 30-hour battery life."
    },
    {
      "id": "SKU002",
      "title": "Organic Cotton T-Shirt",
      "description": "Soft and breathable t-shirt made from 100% organic cotton. Available in various colors."
    }
  ],
  "taxonomy": "Audio > Headphones > Wireless\nApparel > Tops > T-Shirts\nApparel > Tops > Blouses"
}'

(Replace https://your-app-domain.com with the actual application URL and sk_yourGeneratedApiKeyHere_xxxxxxxx with your real API key.)

5. Handling API Responses

a. Success Response (200 OK):

If the request is successful, you'll receive a JSON response like this:

{
  "matches": [
    {
      "id": "SKU001",
      "final_category": "Audio > Headphones > Wireless"
    },
    {
      "id": "SKU002",
      "final_category": "Apparel > Tops > T-Shirts"
    }
  ]
}

• The matches array will contain an object for each product sent, with its id and the final_category path.
• If a product cannot be confidently matched, final_category might be "Other" or a more generic category.

b. Error Responses:

• 400 Bad Request: Issues with your request payload (e.g., missing fields, invalid JSON, too many products). The response body will include an error message.

  { "error": "Products array is required and cannot be empty." }
  

• 401 Unauthorized: API key missing, invalid, or revoked.

  { "error": "Unauthorized: Invalid API key." }
  

• 402 Payment Required: Your account has insufficient credits for the number of products submitted. The response may include creditsNeeded and creditsAvailable.

  { "error": "Insufficient credits.", "creditsNeeded": 2, "creditsAvailable": 0 }
  

• 500 Internal Server Error: An unexpected error occurred on our end. Please try again later or contact support if it persists.

Always check the HTTP status code and parse the JSON error message for details.

6. Rate Limits and Quotas

• Products per Request: Maximum of 100 products.
• Credit Consumption: 2 credits per product matched.
• Standard API rate limits may apply to prevent abuse (details to be provided if specific limits are set beyond product count).

7. Best Practices

• Secure Your API Key: Store it as an environment variable or in a secure secrets manager. Do not embed it directly in client-side code or commit it to repositories.
• Error Handling: Implement robust error handling in your application to manage different API responses gracefully (e.g., retries for transient errors, user notifications for credit issues).
• Batching: For large numbers of products, batch them into requests of up to 100 products.
• Monitor Credits: Keep an eye on your credit balance through the Dashboard to ensure uninterrupted service.

For more detailed information on specific error codes or advanced usage, please refer to the full API Reference Documentation or contact support.