Metadata-Version: 2.5
Name: langchain-apish
Version: 0.1.0
Summary: LangChain tools for API.SH, which turns public web pages from around 1,000 websites into clean JSON: search engines, social media, e-commerce, real estate, jobs, travel, news and sports (Google, Amazon, TikTok, Zillow, LinkedIn and more).
Project-URL: Homepage, https://api.sh
Project-URL: Documentation, https://api.sh/docs
Project-URL: Source, https://github.com/API-SH/langchain-apish
Project-URL: Issues, https://github.com/API-SH/langchain-apish/issues
Author-email: "API.SH" <support@api.sh>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,api.sh,apish,langchain,langgraph,serp,tiktok,tools,web data,zillow
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: <4.0,>=3.10
Requires-Dist: apish-sdk<1,>=0.3.0
Requires-Dist: httpx<1,>=0.24
Requires-Dist: langchain-core<2,>=0.3.49
Requires-Dist: pydantic<3,>=2.7
Description-Content-Type: text/markdown

# langchain-apish

LangChain tools for [API.SH](https://api.sh/?utm_source=github&utm_medium=readme). API.SH turns public web pages
from around 1,000 websites into clean JSON: search engines, social media, e-commerce, real estate, jobs, travel,
news and sports (Google, Amazon, TikTok, Zillow, LinkedIn and more). With this package an agent can find the right
endpoint and call it.

```sh
pip install -U langchain-apish
export APISH_API_KEY="..."        # https://app.api.sh/keys
```

Every account gets free monthly credits. Failed calls are free and there are no rate limits.

## Tools

| Tool | What it does |
| --- | --- |
| `ApishSearchTool` (`apish_search`) | Finds endpoints by keywords: route, what it returns, parameters, price. Free, needs no key |
| `ApishCallTool` (`apish_call`) | Runs any endpoint (`route` + `params`) and returns its JSON |
| `ApishTool(route=...)` | One endpoint as a tool, with its parameters as typed, validated arguments |
| `ApishToolkit` | `apish_search` + `apish_call`, plus one `ApishTool` per route you list |

Two generic tools cover the whole catalog and keep the prompt short. When an agent only needs a few endpoints,
give it typed tools instead: models fill typed arguments more reliably.

## Agent example

`create_agent` builds a LangGraph agent that calls tools in a loop until it can answer:

```python
from langchain.agents import create_agent
from langchain_apish import ApishToolkit

tools = ApishToolkit().get_tools()  # apish_search + apish_call
agent = create_agent("openai:gpt-5-mini", tools)

result = agent.invoke(
    {
        "messages": [
            {"role": "user", "content": "How many followers does NASA have on TikTok, and what are the top 3 posts on r/python right now?"}
        ]
    }
)
print(result["messages"][-1].content)
```

Install the model provider you use (`pip install langchain langchain-openai`, or any other chat model with tool
calling). To limit the agent to fixed endpoints:

```python
toolkit = ApishToolkit(
    routes=["/zillow/v1/search", "/zillow/v1/property"],
    include_generic=False,
)
agent = create_agent("openai:gpt-5-mini", toolkit.get_tools())
```

## Calling a tool directly

```python
from langchain_apish import ApishSearchTool, ApishTool

print(ApishSearchTool().invoke({"query": "tiktok profile", "limit": 3}))

profile = ApishTool(route="/tiktok/v1/profile")
print(profile.args)  # {'username': {...}}
print(profile.invoke({"username": "nasa"}))  # JSON text
```

As a tool call (what an agent sends), the result is a `ToolMessage`: `content` is the JSON text for the model,
and `artifact` holds the parsed data with the request id and credits used:

```python
msg = profile.invoke({"name": profile.name, "args": {"username": "nasa"}, "id": "1", "type": "tool_call"})
msg.artifact["data"]["followers"], msg.artifact["credits_used"], msg.artifact["request_id"]
```

## Async

Every tool supports `ainvoke`, using the async client of [`apish-sdk`](https://pypi.org/project/apish-sdk/):

```python
hits = await ApishSearchTool().ainvoke({"query": "google search"})
page = await ApishTool(route="/google/v1/search").ainvoke({"q": "best running shoes", "country": "us"})
```

## Options

All tools take `api_key` (default: `APISH_API_KEY`), `client` / `async_client` (your own `apish.Apish` /
`apish.AsyncApish`), `raw` (default `False`: leave out the bulky raw source blocks), and `max_chars` (results
longer than this are cut, with a note telling the model to ask for less, e.g. with the `fields` parameter).
`ApishToolkit` passes them to every tool and shares one client between them.

API errors are returned to the model as the tool result (for example `api.sh error 400: url is required`), so
it can fix its parameters and try again.

## Relation to apish-sdk

This package is built on [`apish-sdk`](https://pypi.org/project/apish-sdk/), the official Python client: it
uses the SDK's clients, endpoint list and tool naming. `apish-sdk` also ships a small helper,
`apish.langchain.apish_tools`; the same call works here and returns this package's tools:

```python
from apish import Apish
from langchain_apish import apish_tools  # was: from apish.langchain import apish_tools

tools = apish_tools(Apish())
```

Endpoints released after the installed `apish-sdk` are found through the live catalog
(`https://api.api.sh/catalog`, free) and their parameters are read from the platform's OpenAPI document.

## Development

```sh
uv sync --group test --group lint
uv run pytest tests/unit_tests                      # offline, HTTP mocked
APISH_API_KEY=... uv run pytest tests/integration_tests   # live: a few calls, costs credits
```

## Links

- Docs: https://api.sh/docs?utm_source=github&utm_medium=readme
- MCP server for AI clients: https://api.sh/mcp?utm_source=github&utm_medium=readme
- Status: https://status.api.sh

## License

MIT
