This tutorial will walk you through integrating the kultur.dev Cultural Intelligence API into your application. By the end, you'll be able to query cultural insights programmatically.

Prerequisites

A kultur.dev account (sign up here)
An API key (available in your dashboard)
Basic knowledge of HTTP APIs

Step 1: Get Your API Key

After signing up, navigate to your dashboard and copy your API key. You'll use this to authenticate all requests.

API Key: ck_live_xxxxxxxxxxxxxxxxxxxxx

Keep this key secret. Never expose it in client-side code.

Step 2: Make Your First Request

The simplest way to test the API is with cURL:

curl -X POST https://api.kultur.dev/v1/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the key business etiquette rules in Japan?",
    "markets": ["JP"]
  }'

You'll receive a response like:

{
  "answer": "In Japanese business culture, several key etiquette rules are essential...",
  "confidence": 0.94,
  "sources": ["business_etiquette", "communication_styles"],
  "markets_analyzed": ["JP"]
}

Step 3: Integrate with Python

Here's how to integrate the API into a Python application:

import requests

class kultur.devClient: def __init__(self): self.api_key = os.environ.get("CONTENTRY_API_KEY") self.base_url = "https://api.kultur.dev/v1" def query(self, question, markets): response = requests.post( f"{self.base_url}/query", headers={ "Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json" }, json={ "query": question, "markets": markets } ) response.raise_for_status() return response.json()

# Usage client = kultur.devClient() result = client.query( "What colors should I avoid in marketing materials for China?", markets=["CN"] ) print(result["answer"]) ```

Step 4: Integrate with JavaScript/Node.js

For Node.js applications:

class kultur.devClient { constructor() { this.apiKey = process.env.CONTENTRY_API_KEY; this.baseUrl = 'https://api.kultur.dev/v1'; }

async query(question, markets) { const response = await axios.post( ${this.baseUrl}/query, { query: question, markets: markets }, { headers: { 'Authorization': Bearer ${this.apiKey}, 'Content-Type': 'application/json' } } ); return response.data; } }

// Usage const client = new kultur.devClient(); const result = await client.query( 'What are appropriate business gifts in South Korea?', ['KR'] ); console.log(result.answer); ```

Step 5: Handle Streaming Responses

For complex queries, use our streaming endpoint to get responses as they're generated:

def stream_query(question, markets): response = requests.post( "https://api.kultur.dev/v1/query/stream", headers={ "Authorization": f"Bearer {api_key}", "Content-Type": "application/json" }, json={"query": question, "markets": markets}, stream=True ) for line in response.iter_lines(): if line: print(line.decode('utf-8'))

stream_query("Compare business meeting styles in Germany vs Brazil", ["DE", "BR"]) ```

Common Use Cases

Validate Marketing Content

result = client.query(
    f"Review this marketing copy for cultural appropriateness in India: '{copy}'",
    markets=["IN"]
)

Get Localization Guidance

result = client.query(
    "What product features should we prioritize for the Middle East market?",
    markets=["AE", "SA", "QA"]
)

Check for Sensitivities

result = client.query(
    f"Are there any cultural concerns with using this image in Southeast Asia?",
    markets=["TH", "VN", "ID", "MY"]
)

Error Handling

The API returns standard HTTP status codes:

200: Success
400: Bad request (check your query format)
401: Invalid API key
429: Rate limit exceeded
500: Server error

Always wrap API calls in try/catch blocks and implement exponential backoff for rate limits.

Next Steps

Explore the full API Reference
Check out our SDKs for Python, JavaScript, and more
Join our developer community for support

*Need help? Email us at [email protected] or open an issue in our GitHub repo.*

Getting Started with the Cultural Intelligence API in 5 Minutes