API Documentation - Alternatives.ws

Getting Started

Our API provides access to thousands of software alternatives, categories, and detailed product information. All responses are in JSON format.

Base URL

https://alternatives.ws/api/v1

Authentication

Currently, our API is publicly accessible without authentication. Rate limiting applies: 100 requests per minute per IP address.

Endpoints

GET

/categories

Retrieve all available categories with product counts.

Response Example:

{
  "data": [
    {
      "id": 1,
      "name": "Code Editors & IDEs",
      "slug": "code-editors-ides",
      "description": "Code editors, IDEs, and development environments",
      "icon": "fas fa-code",
      "products_count": 15
    }
  ],
  "meta": {
    "total": 160,
    "per_page": 50
  }
}

GET

/categories/{slug}/products

Get all products in a specific category.

Parameters:

Parameter	Type	Required	Description
slug	string	Required	Category slug (e.g., "code-editors-ides")
page	integer	Optional	Page number for pagination (default: 1)
per_page	integer	Optional	Items per page (default: 20, max: 100)

GET

/products/{slug}

Get detailed information about a specific product.

Response Example:

{
  "data": {
    "id": 1,
    "name": "Visual Studio Code",
    "slug": "visual-studio-code",
    "description": "Free source-code editor with IntelliSense, debugging, and Git integration",
    "website_url": "https://code.visualstudio.com",
    "pricing_type": "free",
    "platforms": ["Windows", "macOS", "Linux"],
    "rating": 4.8,
    "rating_count": 12500,
    "category": {
      "name": "Code Editors & IDEs",
      "slug": "code-editors-ides"
    },
    "alternatives": [
      {
        "name": "Sublime Text",
        "slug": "sublime-text",
        "similarity_score": 85
      }
    ]
  }
}

GET

/search

Search for products across all categories.

Parameters:

Parameter	Type	Required	Description
q	string	Required	Search query (minimum 2 characters)
category	string	Optional	Filter by category slug
pricing	string	Optional	Filter by pricing: free, paid, freemium, open_source

Rate Limiting

To ensure fair usage, we implement the following rate limits:

100 requests per minute per IP address
1000 requests per hour per IP address
10,000 requests per day per IP address

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Error Handling

The API uses conventional HTTP response codes to indicate success or failure:

200 - OK: Request successful
400 - Bad Request: Invalid parameters
404 - Not Found: Resource not found
429 - Too Many Requests: Rate limit exceeded
500 - Internal Server Error: Server error

Error Response Format:

{
  "error": {
    "code": 404,
    "message": "Product not found",
    "details": "The requested product slug does not exist"
  }
}