Metadata-Version: 2.4
Name: igeo-ai
Version: 0.1.0
Summary: Official igeo.ai Public REST API client for Python, using only the standard library.
Author: igeo.ai
License-Expression: MIT
Project-URL: Homepage, https://www.igeo.ai/
Project-URL: Documentation, https://www.igeo.ai/developers/
Keywords: igeo.ai,GEO,AI search,REST,SDK
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# igeo.ai Python SDK

Official Python client for the igeo.ai Public REST API. Requires Python 3.10 or newer and uses only Python's standard library (`urllib`); it has no runtime dependencies.

GEO means Generative Engine Optimization: measuring and improving how brands appear in AI-generated answers. The SDK accesses only the product paths and methods supported by the [published OpenAPI schema](https://api.igeo.ai/public-api.json). Workspace membership, roles, scopes, and the server's public route policy enforce access.

## Install

```sh
python -m pip install igeo-ai
```

The distribution name is `igeo-ai`; the import name is `igeo_ai`. Package preparation and registry publication are separate release steps. Before a registry release is available, install a prepared `.whl` artifact locally with `python -m pip install /path/to/igeo_ai-0.1.0-py3-none-any.whl`.

## Read workspace data

Create a workspace key in [MCP & API keys](https://app.igeo.ai/mcp-api-keys). Store it privately in `IGEO_API_KEY`, and set the selected workspace ID in `IGEO_WORKSPACE_ID`.

```python
import os
from igeo_ai import IgeoClient

workspace_id = os.environ["IGEO_WORKSPACE_ID"]
client = IgeoClient(
    api_key=os.environ["IGEO_API_KEY"],
    workspace_id=workspace_id,
)

workspace = client.get(f"/accounts/{workspace_id}")
prompts = client.get(
    f"/accounts/{workspace_id}/prompts",
    query={"take": 25, "skip": 0},
)
```

Every authenticated request sends `Authorization: Bearer …` and `X-Workspace-Id`. Credentials are supplied explicitly to the client; the SDK does not read environment variables or sign you in automatically. Keep keys out of browser code, source control, URLs, and logs. Read [authentication and permissions](https://www.igeo.ai/developers/auth/) for account requirements, API-key scopes, and roles.

## Requests and pagination

`client.get(path, query=None)` makes one GET request. `client.request(path, method="GET", query=None, body=...)` supports `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`. A provided body is encoded as JSON; a GET cannot contain a body. Omit `body` when no body is intended; `body=None` explicitly sends JSON `null` for an allowed method.

For write operations, retrieve and review the existing resource, then use the exact path, method, and input fields defined by the live schema. This SDK does not create accounts or grant access to private application routes.

Query values can be strings, finite numbers, booleans, `None`, or lists/tuples of those values. Lists become repeated query parameters; `None` values are omitted. Each endpoint's schema determines supported filters and pagination. The client returns one response at a time and does not invent a shared pagination contract for different endpoints.

Responses with a JSON content type are decoded to Python values. Empty successful responses return `None`; other text responses are decoded as UTF-8 strings. Public data shapes are described by the current OpenAPI document, rather than a frozen copy of every product model in this small SDK.

## Origin and credential handling

The default origin is `https://api.igeo.ai`. You can select another trusted HTTPS origin with `base_url`; HTTP is accepted only for loopback local development. Credentials are sent to the chosen origin, so select it deliberately.

Paths must begin with `/` and contain no origin, query string, fragment, backslash, control character, or dot segment. Put query parameters in `query`. HTTP redirects are rejected rather than followed, so the SDK does not forward authentication headers to a redirect target. Client representations redact credentials and workspace IDs; API-error messages omit provider bodies and query strings. This protects ordinary logging and representation, not introspection of a running Python process.

## Timeouts and typed errors

```python
from igeo_ai import IgeoApiError, IgeoTransportError

try:
    result = client.get(f"/accounts/{workspace_id}")
except IgeoApiError as error:
    print({"status": error.status, "retry_after_seconds": error.retry_after_seconds})
except IgeoTransportError as error:
    print({"code": error.code})
```

The `timeout` constructor option defaults to 15 seconds and must be greater than zero and at most 300. It is the standard-library timeout for blocking socket operations, including response reading; it is not a total wall-clock deadline or an asynchronous cancellation mechanism.

`IgeoApiError` exposes `status`, parsed `body`, optional `request_id`, and `retry_after_seconds` when a valid `Retry-After` value is available. The `body` can contain private data; avoid logging it without review. `IgeoTransportError.code` is `NETWORK_ERROR`, `TIMEOUT`, or `INVALID_RESPONSE`.

Each call makes **one request**. There are no automatic retries for reads, writes, timeouts, rate limits, or server errors. For retryable reads, use bounded backoff and honor `Retry-After`. For a timed-out write, inspect the current resource before deciding whether to repeat it: a timeout does not prove the operation failed, and no universal idempotency-key behavior is assumed.

## Read the public schema anonymously

```python
from igeo_ai import get_public_schema

schema = get_public_schema()
print(list(schema["paths"]))
```

This helper fetches `/public-api.json` without credentials and verifies that the response includes an OpenAPI version and a paths object. Optional arguments are `base_url` and `timeout`.

For conversational agents, connect an MCP client to `https://api.igeo.ai/mcp` using the [MCP setup guide](https://www.igeo.ai/developers/mcp/). This Python package is a synchronous REST client, not a local MCP server.

## Verify and package

Run the mocked unit tests from the package directory:

```sh
PYTHONPATH=src python -m unittest discover -s tests -v
```

With Python's `build` frontend installed in an isolated development environment, `python -m build` creates a wheel and source distribution. The wheel lists only `igeo_ai` and its typing marker. `MANIFEST.in` explicitly lists source-release files; no application code, account credentials, or monorepo configuration is part of this package. Tests use mocked responses and never read real keys or call a workspace.

The included MIT license applies to the new SDK code in this distribution. Access to igeo.ai and use of API data remain subject to the [product terms](https://www.igeo.ai/terms-and-conditions/) and documented data-use terms.

[igeo.ai](https://www.igeo.ai/) · [developer documentation](https://www.igeo.ai/developers/) · [REST API guide](https://www.igeo.ai/developers/api/) · support@igeo.ai.
