🔌 Spinny API Reference

Complete endpoint documentation for extracting real-time automotive data from India's fastest-growing used car marketplace

API Overview

Base URL: https://api.carapis.com/v1/parsers/spinny
Authentication: Bearer token required
Rate Limits: 1,000 requests/day (free), 10,000 requests/day (pro)
Response Format: JSON
Timezone: Asia/Kolkata (UTC+5:30)

🔑 Authentication

All API requests require authentication using a Bearer token in the Authorization header:

Authorization: Bearer spinny_parser_sk_your_api_key_here

API Key Format

Your Spinny API key follows this pattern: spinny_parser_sk_ followed by a 32-character hexadecimal string.

📡 Endpoints

Search Vehicles

Search for vehicles with various filters and parameters.

Endpoint: GET /search

Parameters:

Parameter	Type	Required	Description	Example
`make`	string	No	Vehicle brand	"Maruti Suzuki", "Hyundai"
`model`	string	No	Vehicle model	"Swift", "i20"
`city`	string	No	City name	"Mumbai", "Delhi", "Bangalore"
`year_min`	integer	No	Minimum year	2018
`year_max`	integer	No	Maximum year	2024
`price_min`	integer	No	Minimum price (INR)	300000
`price_max`	integer	No	Maximum price (INR)	1500000
`fuel_type`	string	No	Fuel type	"Petrol", "Diesel"
`transmission`	string	No	Transmission	"Manual", "Automatic"
`quality_rating`	string	No	Quality rating	"excellent", "good", "fair"
`body_type`	string	No	Body type	"Hatchback", "Sedan", "SUV"
`limit`	integer	No	Results per page (max 100)	25
`page`	integer	No	Page number	1

Example Request:

curl -X GET "https://api.carapis.com/v1/parsers/spinny/search" \
  -H "Authorization: Bearer spinny_parser_sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -G \
  -d "make=Maruti Suzuki" \
  -d "city=Mumbai" \
  -d "year_min=2018" \
  -d "limit=10"

Example Response:

{
  "success": true,
  "data": {
    "vehicles": [
      {
        "id": "spinny_12345",
        "title": "2019 Maruti Suzuki Swift VXI",
        "price": {
          "fixed_price": 650000,
          "currency": "INR",
          "emi_monthly": 12500,
          "down_payment": 130000,
          "negotiable": false
        },
        "specifications": {
          "make": "Maruti Suzuki",
          "model": "Swift",
          "year": 2019,
          "variant": "VXI",
          "engine": "1.2L K-Series",
          "transmission": "Manual",
          "mileage": 25000,
          "fuel_type": "Petrol",
          "body_type": "Hatchback"
        },
        "quality_assurance": {
          "inspection_score": 95,
          "quality_rating": "excellent"
        },
        "location": {
          "city": "Mumbai",
          "dealer_name": "Spinny Mumbai Central"
        },
        "url": "https://www.spinny.com/used-cars/mumbai/maruti-suzuki-swift-vxi-2019",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "total_results": 1250,
    "page": 1,
    "limit": 10
  }
}

Get Vehicle Details

Retrieve detailed information about a specific vehicle.

Endpoint: GET /vehicle/\{vehicle_id\}

Parameters:

Parameter	Type	Required	Description
`vehicle_id`	string	Yes	Unique vehicle identifier

Example Request:

curl -X GET "https://api.carapis.com/v1/parsers/spinny/vehicle/12345" \
  -H "Authorization: Bearer spinny_parser_sk_your_api_key_here" \
  -H "Content-Type: application/json"

Example Response:

{
  "success": true,
  "data": {
    "vehicle": {
      "id": "spinny_12345",
      "title": "2019 Maruti Suzuki Swift VXI",
      "price": {
        "fixed_price": 650000,
        "currency": "INR",
        "emi_monthly": 12500,
        "down_payment": 130000,
        "negotiable": false,
        "insurance_estimate": 15000
      },
      "specifications": {
        "make": "Maruti Suzuki",
        "model": "Swift",
        "year": 2019,
        "variant": "VXI",
        "engine": "1.2L K-Series",
        "transmission": "Manual",
        "mileage": 25000,
        "fuel_type": "Petrol",
        "body_type": "Hatchback",
        "color": "Pearl Arctic White",
        "seats": 5,
        "doors": 5
      },
      "quality_assurance": {
        "inspection_score": 95,
        "quality_rating": "excellent",
        "inspection_date": "2024-01-15",
        "warranty_months": 12,
        "service_history": "complete",
        "inspection_report": {
          "engine_performance": "excellent",
          "exterior_condition": "excellent",
          "interior_condition": "excellent",
          "safety_features": "excellent"
        }
      },
      "location": {
        "city": "Mumbai",
        "state": "Maharashtra",
        "dealer_name": "Spinny Mumbai Central",
        "dealer_address": "123, Andheri West, Mumbai",
        "home_delivery": true,
        "delivery_cost": 0
      },
      "features": ["Power Steering", "Air Conditioning", "Power Windows", "Central Locking", "Music System", "ABS", "Airbags"],
      "financing": {
        "available": true,
        "partners": ["HDFC Bank", "ICICI Bank"],
        "interest_rate": "8.5%",
        "tenure_options": [12, 24, 36, 48, 60]
      },
      "url": "https://www.spinny.com/used-cars/mumbai/maruti-suzuki-swift-vxi-2019",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:15:00Z"
    }
  }
}

Get Makes

Retrieve list of available vehicle makes.

Endpoint: GET /makes

Parameters: None

Example Request:

curl -X GET "https://api.carapis.com/v1/parsers/spinny/makes" \
  -H "Authorization: Bearer spinny_parser_sk_your_api_key_here" \
  -H "Content-Type: application/json"

Example Response:

{
  "success": true,
  "data": {
    "makes": [
      {
        "name": "Maruti Suzuki",
        "count": 15420,
        "popular_models": ["Swift", "Dzire", "Brezza"]
      },
      {
        "name": "Hyundai",
        "count": 12850,
        "popular_models": ["i20", "Verna", "Creta"]
      },
      {
        "name": "Honda",
        "count": 8250,
        "popular_models": ["City", "Amaze", "WR-V"]
      },
      {
        "name": "Toyota",
        "count": 6250,
        "popular_models": ["Innova", "Fortuner", "Camry"]
      }
    ]
  }
}

Get Models

Retrieve models for a specific make.

Endpoint: GET /makes/\{make\}/models

Parameters:

Parameter	Type	Required	Description
`make`	string	Yes	Make name (e.g., "Maruti Suzuki")

Example Request:

curl -X GET "https://api.carapis.com/v1/parsers/spinny/makes/Maruti%20Suzuki/models" \
  -H "Authorization: Bearer spinny_parser_sk_your_api_key_here" \
  -H "Content-Type: application/json"

Example Response:

{
  "success": true,
  "data": {
    "make": "Maruti Suzuki",
    "models": [
      {
        "name": "Swift",
        "count": 3250,
        "years": [2018, 2019, 2020, 2021, 2022, 2023, 2024]
      },
      {
        "name": "Dzire",
        "count": 2800,
        "years": [2018, 2019, 2020, 2021, 2022, 2023, 2024]
      },
      {
        "name": "Brezza",
        "count": 1850,
        "years": [2019, 2020, 2021, 2022, 2023, 2024]
      }
    ]
  }
}

Get Cities

Retrieve list of available cities.

Endpoint: GET /cities

Parameters: None

Example Request:

curl -X GET "https://api.carapis.com/v1/parsers/spinny/cities" \
  -H "Authorization: Bearer spinny_parser_sk_your_api_key_here" \
  -H "Content-Type: application/json"

Example Response:

{
  "success": true,
  "data": {
    "cities": [
      {
        "name": "Mumbai",
        "state": "Maharashtra",
        "count": 8500,
        "launch_date": "2015-01-01"
      },
      {
        "name": "Delhi NCR",
        "state": "Delhi/Haryana",
        "count": 12000,
        "launch_date": "2016-03-15"
      },
      {
        "name": "Bangalore",
        "state": "Karnataka",
        "count": 9200,
        "launch_date": "2017-06-20"
      },
      {
        "name": "Hyderabad",
        "state": "Telangana",
        "count": 6800,
        "launch_date": "2018-09-10"
      }
    ]
  }
}

Get Market Statistics

Retrieve market statistics and trends.

Endpoint: GET /statistics

Parameters:

Parameter	Type	Required	Description	Example
`make`	string	No	Filter by make	"Maruti Suzuki"
`city`	string	No	Filter by city	"Mumbai"
`period`	string	No	Time period	"30d", "90d", "1y"

Example Request:

curl -X GET "https://api.carapis.com/v1/parsers/spinny/statistics?make=Maruti Suzuki&city=Mumbai&period=30d" \
  -H "Authorization: Bearer spinny_parser_sk_your_api_key_here" \
  -H "Content-Type: application/json"

Example Response:

{
  "success": true,
  "data": {
    "statistics": {
      "total_listings": 15420,
      "average_price": 850000,
      "price_range": {
        "min": 300000,
        "max": 2500000
      },
      "quality_distribution": {
        "excellent": 45.2,
        "good": 38.8,
        "fair": 16.0
      },
      "popular_models": [
        {
          "name": "Swift",
          "count": 3250,
          "avg_price": 750000
        },
        {
          "name": "Dzire",
          "count": 2800,
          "avg_price": 850000
        }
      ],
      "price_trends": [
        {
          "date": "2024-01-01",
          "avg_price": 840000,
          "listings": 15200
        },
        {
          "date": "2024-01-15",
          "avg_price": 850000,
          "listings": 15420
        }
      ]
    }
  }
}

📊 Response Codes

Status Code	Description
`200`	Success
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource not found
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

🔧 Error Responses

Authentication Error

{
  "success": false,
  "error": {
    "code": "AUTH_ERROR",
    "message": "Invalid API key",
    "details": "The provided API key is invalid or expired"
  }
}

Validation Error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid parameters",
    "details": {
      "price_min": "Must be a positive integer",
      "year_max": "Must be between 1990 and 2024"
    }
  }
}

Rate Limit Error

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": {
      "limit": 1000,
      "reset_time": "2024-01-21T00:00:00Z"
    }
  }
}

🚨 Rate Limits

Rate Limit Information

Free Plan: 1,000 requests per day
Pro Plan: 10,000 requests per day
Enterprise: Custom limits available
Reset Time: Daily at 00:00 UTC

Rate Limit Headers

The API includes rate limit information in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 850
X-RateLimit-Reset: 1705795200

📝 Code Examples

Python SDK

import requests
from typing import Dict, List, Optional

class SpinnyAPI:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://api.carapis.com/v1/parsers/spinny"
        self.headers = {
            "Authorization": f"Bearer \{api_key\}",
            "Content-Type": "application/json"
        }

    def search_vehicles(self, **params) -> Dict:
        """Search for vehicles with filters"""
        response = requests.get(f"{self.base_url}/search",
                              headers=self.headers, params=params)
        response.raise_for_status()
        return response.json()

    def get_vehicle(self, vehicle_id: str) -> Dict:
        """Get detailed vehicle information"""
        response = requests.get(f"{self.base_url}/vehicle/\{vehicle_id\}",
                              headers=self.headers)
        response.raise_for_status()
        return response.json()

    def get_makes(self) -> Dict:
        """Get available makes"""
        response = requests.get(f"{self.base_url}/makes",
                              headers=self.headers)
        response.raise_for_status()
        return response.json()

    def get_models(self, make: str) -> Dict:
        """Get models for a specific make"""
        response = requests.get(f"{self.base_url}/makes/\{make\}/models",
                              headers=self.headers)
        response.raise_for_status()
        return response.json()

# Usage
api = SpinnyAPI("spinny_parser_sk_your_api_key_here")

# Search for Maruti Suzuki cars
results = api.search_vehicles(make="Maruti Suzuki", city="Mumbai", limit=10)

# Get vehicle details
vehicle = api.get_vehicle("12345")

JavaScript SDK

class SpinnyAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.carapis.com/v1/parsers/spinny';
    this.headers = {
      Authorization: `Bearer $\{apiKey\}`,
      'Content-Type': 'application/json',
    };
  }

  async searchVehicles(params = {}) {
    const queryString = new URLSearchParams(params).toString();
    const response = await fetch(`${this.baseUrl}/search?$\{queryString\}`, {
      method: 'GET',
      headers: this.headers,
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    return await response.json();
  }

  async getVehicle(vehicleId) {
    const response = await fetch(`${this.baseUrl}/vehicle/$\{vehicleId\}`, {
      method: 'GET',
      headers: this.headers,
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    return await response.json();
  }

  async getMakes() {
    const response = await fetch(`${this.baseUrl}/makes`, {
      method: 'GET',
      headers: this.headers,
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    return await response.json();
  }

  async getModels(make) {
    const response = await fetch(`${this.baseUrl}/makes/$\{make\}/models`, {
      method: 'GET',
      headers: this.headers,
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    return await response.json();
  }
}

// Usage
const api = new SpinnyAPI('spinny_parser_sk_your_api_key_here');

// Search for Hyundai cars
api
  .searchVehicles({ make: 'Hyundai', city: 'Delhi', limit: 10 })
  .then((results) => console.log(results))
  .catch((error) => console.error(error));

// Get vehicle details
api
  .getVehicle('12345')
  .then((vehicle) => console.log(vehicle))
  .catch((error) => console.error(error));

🔄 Webhooks

Webhook Support

Webhooks are available for real-time data updates. Contact our support team to set up webhook notifications for new listings and price changes.

Webhook Events

Event	Description
`vehicle.created`	New vehicle listing added
`vehicle.updated`	Vehicle information updated
`vehicle.removed`	Vehicle listing removed
`price.changed`	Vehicle price changed
`quality.updated`	Quality inspection updated

Webhook Payload

{
  "event": "vehicle.created",
  "timestamp": "2024-01-20T14:30:00Z",
  "data": {
    "vehicle_id": "12345",
    "title": "2019 Maruti Suzuki Swift VXI",
    "price": 650000,
    "city": "Mumbai",
    "quality_rating": "excellent"
  }
}

📞 Support

Need Help?

API Status - Check API availability
Documentation - Complete documentation
Support - Contact our team
Community - Developer community

Ready to start? Get your API key and begin extracting Spinny data today!

🔑 Authentication​

📡 Endpoints​

Search Vehicles​

Get Vehicle Details​

Get Makes​

Get Models​

Get Cities​

Get Market Statistics​

📊 Response Codes​

🔧 Error Responses​

Authentication Error​

Validation Error​

Rate Limit Error​

🚨 Rate Limits​

Rate Limit Headers​

📝 Code Examples​

Python SDK​

JavaScript SDK​

🔄 Webhooks​

Webhook Events​

Webhook Payload​

📞 Support​

🔑 Authentication

📡 Endpoints

Search Vehicles

Get Vehicle Details

Get Makes

Get Models

Get Cities

Get Market Statistics

📊 Response Codes

🔧 Error Responses

Authentication Error

Validation Error

Rate Limit Error

🚨 Rate Limits

Rate Limit Headers

📝 Code Examples

Python SDK

JavaScript SDK

🔄 Webhooks

Webhook Events

Webhook Payload

📞 Support