​
Overview

The SG Cars Trends API uses Bearer Token authentication for secure access to protected endpoints. Most API endpoints require authentication, with the exception of health checks and some workflow endpoints.

​
API Key Requirements

Protected Endpoints

  • All /v1/* endpoints (cars, coe, months data)
  • /workflows/trigger endpoint

Public Endpoints

  • /health endpoint
  • Individual workflow endpoints (/workflows/cars, /workflows/coe)
  • Social media webhook endpoints

​
Getting Your API Key

API keys are currently issued on a case-by-case basis. To request an API key:
  1. Create an issue in our GitHub repository
  2. Describe your use case and expected usage volume
  3. Provide your contact information
  4. Wait for approval and key issuance

​
Using Your API Key

​
Bearer Token Format

Include your API key in the Authorization header using the Bearer token format: 
Authorization: Bearer YOUR_API_KEY

​
Request Examples

curl -X GET \
  "https://api.sgcarstrends.com/v1/cars" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

​
Authentication Errors

​
Common Error Responses

{
  "success": false,
  "error": "Missing Authorization header",
  "code": 401
}

​
Rate Limiting

The API implements rate limiting based on your authentication status:
Authentication StatusRate LimitWindow
Authenticated100 requests1 minute
Unauthenticated10 requests1 minute

​
Rate Limit Headers

Rate limit information is included in response headers: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

​
Rate Limit Exceeded

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response: 
{
  "success": false,
  "error": "Rate limit exceeded. Please try again later.",
  "code": 429,
  "retry_after": 60
}

​
Best Practices

​
1. Secure Storage

Never expose your API key in client-side code, public repositories, or logs.
Do:
  • Store API keys in environment variables
  • Use secure key management systems
  • Rotate keys regularly
Don’t:
  • Hardcode keys in your application
  • Commit keys to version control
  • Share keys in plain text

​
2. Error Handling

Always implement proper error handling for authentication failures: 
try {
  const response = await fetch('https://api.sgcarstrends.com/v1/cars', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
  });
  
  if (!response.ok) {
    if (response.status === 401) {
      throw new Error('Authentication failed. Check your API key.');
    }
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  
  const data = await response.json();
  return data;
} catch (error) {
  console.error('API request failed:', error.message);
  throw error;
}

​
3. Respect Rate Limits

Implement backoff strategies when hitting rate limits: 
async function makeAPIRequest(url, options = {}) {
  const maxRetries = 3;
  let retryCount = 0;
  
  while (retryCount < maxRetries) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || 60;
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        retryCount++;
        continue;
      }
      
      return response;
    } catch (error) {
      retryCount++;
      if (retryCount === maxRetries) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * retryCount));
    }
  }
}

​
Environment Variables

Store your API key as an environment variable: 
SG_CARS_TRENDS_API_KEY=your_api_key_here

​
Next Steps

API Reference

Explore all available endpoints

Data Models

Understand the data structure