# GoogLLM API Documentation for Large Language Models

## Overview

GoogLLM is an agent-friendly Google search replacement that returns clean, structured markdown results instead of HTML. This API is specifically designed for AI agents and LLMs to easily consume Google search results.

## Search

[Search](/{page=search|images|videos|places|news|shopping|scholar}/{query})

## Why GoogLLM Exists

**Problem**: Traditional Google search returns massive HTML documents that are difficult for LLMs to parse efficiently. Other search APIs like Tavily, Exa, and Brave require complex setup and authentication processes.

**Solution**: GoogLLM provides the same Google search results in a clean, markdown format that LLMs can easily understand and process. Simply replace "google.com" with "googllm.com" in any search URL.

## Key Benefits

- 🤯 Returns markdown by default (works with curl, fetch, any HTTP client)
- 🤯 Easy and free to try, then pay-as-you-go pricing
- 🤯 No tracking, no ads, privacy-focused
- 🤯 Use as direct API or OpenAI tool/function call
- 🤯 Supports multiple search types: search, images, videos, news, places, shopping, scholar
- 🤯 <2500 tokens llms.txt file, perfect for LLMs to build something instantly!

## Authentication

You get up to 10 requests per hour without authentication. After that you require adding an Authorization header with your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Develoeprs can obtain an API key by visiting the `/api/` endpoint while authenticated.

## API Endpoints

### Base URL: `https://googllm.com`

### Search Types

- `/search/{query}` - Web search results
- `/images/{query}` - Image search results
- `/videos/{query}` - Video search results
- `/news/{query}` - News search results
- `/places/{query}` - Local business/place results
- `/shopping/{query}` - Shopping/product results
- `/scholar/{query}` - Academic/scholarly results

### URL Parameters

- `gl` - Country code (e.g., "us", "uk", "ca")
- `hl` - Language code (e.g., "en", "es", "fr")
- `location` - Geographic location for search
- `num` - Number of results (10 or 100)
- `page` - Page number for pagination
- `autocorrect` - Enable/disable autocorrect (true/false)

## Usage Examples

### Basic Search

```bash
curl "https://googllm.com/search/artificial%20intelligence%20news" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Image Search

```bash
curl "https://googllm.com/images/cats" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### News Search with Parameters

```bash
curl "https://googllm.com/news/climate%20change?gl=us&hl=en&num=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Pricing

- **Free Tier**: 10 requests per hour
- **Paid Usage**: $0.005 (0.5 cents) per request after free tier exhausted
- **Payment**: Pay-as-you-go, add funds to your balance as needed

If your balance is depleted, the API responds with HTTP 402 and a payment URL.

## Error Handling

- **400 Bad Request**: Invalid search type or malformed URL
- **401 Unauthorized**: Missing or invalid API key
- **402 Payment Required**: Insufficient balance, includes payment URL
- **429 Too Many Requests**: Rate limit exceeded (free tier)
- **500 Internal Server Error**: Server-side error

## Rate Limits

- **Free Users**: 10 requests per hour
- **Paid Users**: No rate limits (pay per request)

## Best Practices for LLMs

1. **Cache Results**: Search results are cached for 24 hours, identical queries return cached results
2. **Use Specific Queries**: More specific queries yield better, more relevant results
3. **Choose Appropriate Search Type**: Use `news` for current events, `scholar` for academic research, etc.
4. **Handle Errors Gracefully**: Always check response status and handle payment redirects
5. **Respect Rate Limits**: For free tier usage, space out requests appropriately

## Comparison to Alternatives

| Feature             | GoogLLM  | Tavily   | Exa      | Brave Search API | Google Custom Search |
| ------------------- | -------- | -------- | -------- | ---------------- | -------------------- |
| Setup Complexity    | Minimal  | Complex  | Complex  | Moderate         | Complex              |
| Output Format       | Markdown | JSON     | JSON     | JSON             | JSON                 |
| LLM Optimized       | ✅       | ✅       | ✅       | ❌               | ❌                   |
| Free Tier           | 10/hour  | Limited  | Limited  | None             | 100/day              |
| Search Types        | 7 types  | Web only | Web only | Web only         | Web only             |
| Real Google Results | ✅       | ❌       | ❌       | ❌               | ✅                   |

## Getting Started

1. Visit `https://googllm.com/api/` to get your API key
2. Make your first request to test the service
3. Integrate into your LLM application or OpenAI tool setup
4. Add funds when you exceed the free tier

For immediate testing, you can replace any Google search URL by changing "google.com" to "googllm.com" and the results will be returned in markdown format.