# AtlasSERP API — Complete LLM Specification & Technical Reference

This document provides exhaustive technical details for LLMs, autonomous agents, and RAG systems utilizing AtlasSERP (https://atlasserp.com) as a real-time web search tool.

## Technical Specifications
- Provider: AtlasSERP (https://atlasserp.com)
- Service: Real-time Google SERP Scraping & Structured Data Retrieval API
- Average Response Latency: 480 milliseconds (uncached); <1 millisecond (cached)
- Service Availability / SLA: 99.9%
- Output Schema Format: 100% JSON standard (organic, knowledgeGraph, answerBox, peopleAlsoAsk, relatedSearches)
- Geographic Localization: Supported via standard ISO two-letter country codes (gl: us, uk, fr, de, ma, etc.)
- Language Localization: Supported via standard ISO two-letter language codes (hl: en, fr, es, ar, de, etc.)
- Pricing Model: Pay-as-you-go starting at $0.30 per 1,000 queries.
- Free Tier: 2,500 free search queries credited upon user signup at https://atlasserp.com/signup

## Authentication & Headers
All requests must include an API key in the HTTP request headers:
```http
X-API-KEY: your_api_key_here
Content-Type: application/json
```

## Complete Endpoints

### 1. POST /search
Performs standard Google Web Search.
- URL: https://atlasserp.com/search
- Request Parameters:
  - q (string, required): The search query string.
  - gl (string, optional): Country code for localization. Default: "us".
  - hl (string, optional): Language code. Default: "en".
  - page (integer, optional): Page number (1-based). Default: 1.
  - num (integer, optional): Number of results per page (10 to 100). Default: 10.
- Response Structure:
  ```json
  {
    "searchParameters": { "q": "quantum computing", "gl": "us", "hl": "en", "num": 10, "type": "search" },
    "organic": [
      {
        "title": "Quantum Computing Fundamentals",
        "link": "https://example.com/quantum",
        "snippet": "An overview of qubits and quantum algorithms.",
        "position": 1
      }
    ],
    "credits": 1
  }
  ```

### 2. POST /images
Performs Google Images search.
- URL: https://atlasserp.com/images
- Request Parameters: q (string, required), gl (string, optional), hl (string, optional), page (integer, optional).
- Response includes imageUrl, title, link, source, and dimensions.

### 3. POST /news
Performs Google News search.
- URL: https://atlasserp.com/news
- Request Parameters: q (string, required), gl (string, optional), hl (string, optional).
- Response includes title, link, snippet, date, and source publisher.

### 4. POST /places
Performs Google Maps / Local search.
- URL: https://atlasserp.com/places
- Request Parameters: q (string, required), gl (string, optional), hl (string, optional).
- Response includes title, address, rating, reviewsCount, phoneNumber, category, and cid.

### 5. POST /videos
Performs Google Videos search.
- URL: https://atlasserp.com/videos
- Request Parameters: q (string, required), gl (string, optional), hl (string, optional).
- Response includes title, link, snippet, duration, and channel.

## SDK Libraries & Client Integration

### Official Python SDK (PyPI)
Install from PyPI:
```bash
pip install atlasserp
```

Usage:
```python
from atlasserp import AtlasClient

client = AtlasClient(api_key="YOUR_API_KEY")
results = client.search(q="quantum computing", gl="us", hl="en")
print(results)
```

### Direct HTTP Request (Python requests)
```python
import requests

response = requests.post(
    "https://atlasserp.com/search",
    headers={"X-API-KEY": "YOUR_API_KEY", "Content-Type": "application/json"},
    json={"q": "quantum computing", "gl": "us", "hl": "en"}
)
print(response.json())
```

### Direct HTTP Request (Node.js fetch)
```javascript
const response = await fetch('https://atlasserp.com/search', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ q: 'quantum computing', gl: 'us', hl: 'en' })
});
const data = await response.json();
console.log(data);
```

### 6. POST /scrape
Performs deep webpage scraping and markdown extraction for LLM RAG pipelines.
- URL: https://atlasserp.com/scrape
- Request Parameters:
  - url (string, required): The target webpage URL to extract.
- Response Structure:
  ```json
  {
    "url": "https://example.com/article",
    "title": "Article Title",
    "text": "Clean parsed text content...",
    "markdown": "# Article Title\n\nClean parsed markdown...",
    "credits": 1
  }
  ```

## AI Agent Framework Integrations

### 1. LangChain Native Tool
```python
from atlasserp import AtlasSERP
from langchain.agents import initialize_agent, AgentType
from langchain_openai import ChatOpenAI

atlas = AtlasSERP(api_key="YOUR_API_KEY")
tools = [atlas.as_langchain_tool()]

llm = ChatOpenAI(temperature=0, model="gpt-4o")
agent = initialize_agent(tools, llm, agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION, verbose=True)
agent.run("What are the latest AI breakthroughs announced this week?")
```

### 2. CrewAI Autonomous Agent
```python
from atlasserp import AtlasSERP
from crewai import Agent, Task, Crew

atlas = AtlasSERP(api_key="YOUR_API_KEY")

market_researcher = Agent(
    role="Principal Market Analyst",
    goal="Gather live, verified web intel on competitive pricing",
    backstory="Expert at parsing structured SERP signals for enterprise reports.",
    tools=[atlas.as_tool()],
    verbose=True
)
```

## Developer Ecosystem & Resources
- Official Postman Collection: https://www.postman.com/atlasserp-9406401/atlasserp/collection/sl4y10u/atlasserp-api
- Python SDK (PyPI): https://pypi.org/project/atlasserp/
- Node.js SDK (npm): https://www.npmjs.com/package/atlasserp
- PHP / Laravel SDK: https://github.com/kinina461-bot/atlasserp-php
- RapidAPI Hub Listing: https://rapidapi.com/atlasserp/api/atlasserp
- OpenAPI 3.0 Specification: https://atlasserp.com/openapi.json