SynthientPy

https://github.com/synthient/synthientpy
Admin
SynthientPy is a strongly typed Python client for the Synthient API that provides IP intelligence...
Tokens:6,992
Snippets:52
Trust Score:6.7
License:Apache-2.0
Update:6 months ago
Show doc for...
Tokens:
Raw
### Setup local development environment

Source: https://github.com/synthient/synthientpy/blob/main/CONTRIBUTING.md

Commands to clone the repository, install dependencies using Poetry, and create a new development branch.

```bash
git clone git@github.com:your_name_here/synthientpy.git
poetry install -E test -E doc -E dev
git checkout -b name-of-your-bugfix-or-feature
```

--------------------------------

### Install synthientpy Python Package

Source: https://github.com/synthient/synthientpy/blob/main/README.md

Instructions for installing the synthientpy Python package using pip for MacOS/Linux and Windows.

```bash
pip3 install synthientpy
```

```bat
pip install synthientpy
```

--------------------------------

### API Error Handling (Python)

Source: https://context7.com/synthient/synthientpy/llms.txt

Demonstrates how to handle potential API errors using try-except blocks. It specifically catches `synthient.ErrorResponse` for client-side errors (4xx) and `synthient.InternalServerError` for server-side errors (5xx). Includes examples for both synchronous and asynchronous clients.

```python
import synthientpy as synthient

client = synthient.Client(api_key="sk_your_api_key")

try:
    response = client.lookup_ip("invalid_ip_address")
except synthient.ErrorResponse as e:
    # Raised for 400, 401, 404, 422 errors
    print(f"API Error: {e.message}")
    # Examples:
    # - "Invalid API key" (401)
    # - "Invalid IP address" (422)
    # - "IP not found" (404)
except synthient.InternalServerError as e:
    # Raised for 500+ server errors
    print(f"Server Error: {e}")

# Async error handling
async def safe_lookup(ip: str):
    client = synthient.AsyncClient(api_key="sk_your_api_key")
    try:
        return await client.lookup_ip(ip)
    except synthient.ErrorResponse as e:
        print(f"Error looking up {ip}: {e.message}")
        return None
    except synthient.InternalServerError:
        print(f"Server error while looking up {ip}")
        return None
```

--------------------------------

### Initialize Synthient Client

Source: https://github.com/synthient/synthientpy/blob/main/README.md

Demonstrates how to initialize the synchronous and asynchronous Synthient clients with an API key.

```python
import synthientpy as synthient

client = synthient.Client(api_key="sk_...")
```

```python
import asyncio
import synthientpy as synthient

async def main():
    client = synthient.AsyncClient(api_key="sk_...")

asyncio.run(main())
```

--------------------------------

### Initialize SynthientPy Client (Python)

Source: https://context7.com/synthient/synthientpy/llms.txt

Demonstrates how to create synchronous and asynchronous client instances for the Synthient API using an API key. Supports custom timeout and proxy configurations.

```python
import synthientpy as synthient

# Basic synchronous client
client = synthient.Client(api_key="sk_your_api_key")

# Client with custom timeout (seconds) and proxy
client = synthient.Client(
    api_key="sk_your_api_key",
    default_timeout=10,
    proxy="http://proxy.example.com:8080"
)

# Asynchronous client
async_client = synthient.AsyncClient(
    api_key="sk_your_api_key",
    default_timeout=5,
    proxy=None
)
```

--------------------------------

### Client Initialization

Source: https://context7.com/synthient/synthientpy/llms.txt

Initialize the synchronous or asynchronous Synthient client with your API key. Optional parameters include custom timeout and proxy settings.

```APIDOC
## Client Initialization

Create a synchronous or asynchronous client instance with your API key. Optional parameters include custom timeout and proxy settings.

### Request Body

- **api_key** (string) - Required - Your Synthient API key.
- **default_timeout** (integer) - Optional - Default timeout in seconds for requests.
- **proxy** (string) - Optional - URL for a proxy server (e.g., "http://proxy.example.com:8080").

### Request Example

```python
import synthientpy as synthient

# Basic synchronous client
client = synthient.Client(api_key="sk_your_api_key")

# Client with custom timeout (seconds) and proxy
client = synthient.Client(
    api_key="sk_your_api_key",
    default_timeout=10,
    proxy="http://proxy.example.com:8080"
)

# Asynchronous client
async_client = synthient.AsyncClient(
    api_key="sk_your_api_key",
    default_timeout=5,
    proxy=None
)
```
```

--------------------------------

### Perform Async Credits Check (Python)

Source: https://context7.com/synthient/synthientpy/llms.txt

Demonstrates how to asynchronously retrieve the credit balance information for a Synthient API account using the `AsyncClient`. This allows checking credits without blocking the event loop.

```python
import asyncio
import synthientpy as synthient

async def check_credits():
    client = synthient.AsyncClient(api_key="sk_your_api_key")
    credits_info = await client.credits()
    print(credits_info)

asyncio.run(check_credits())
```

--------------------------------

### Perform IP Lookup with SynthientPy

Source: https://context7.com/synthient/synthientpy/llms.txt

This snippet demonstrates how to initialize the SynthientPy client, perform an IP lookup, and access various data fields from the strongly-typed Pydantic response model. It shows how to retrieve IP data, network information (ASN, ISP), geolocation, and device details.

```python
import synthientpy as synthient
from synthientpy.models import (
    IPLookupResponse,
    IPData,
    Network,
    Location,
    Device,
    EnrichedEntry,
    ProxyEvent,
    FeedFormat,
    SortOrder,
)

client = synthient.Client(api_key="sk_your_api_key")
response: IPLookupResponse = client.lookup_ip("8.8.8.8")

# All fields are typed and validated by Pydantic
ip_data: IPData = response.ip_data
network: Network | None = response.network
location: Location | None = response.location

# Access nested typed objects
if network:
    asn: int = network.asn
    isp: str = network.isp
    network_type: str = network.type

if location:
    country: str = location.country
    latitude: float = location.latitude
    longitude: float = location.longitude
```

--------------------------------

### Check SynthientPy Account Credits (Python)

Source: https://context7.com/synthient/synthientpy/llms.txt

Shows how to retrieve the current credit balance for an authenticated Synthient API account using the synchronous client. The output includes total, used, and remaining credits.

```python
import synthientpy as synthient

client = synthient.Client(api_key="sk_your_api_key")

# Get credit information
credits_info = client.credits()
print(credits_info)
# Example output: {'credits': 10000, 'used': 500, 'remaining': 9500}
```

--------------------------------

### Perform Async IP Lookup (Python)

Source: https://context7.com/synthient/synthientpy/llms.txt

Demonstrates how to perform asynchronous IP lookups using `AsyncClient` for non-blocking operations in Python applications. This is useful for improving performance in I/O-bound tasks.

```python
import asyncio
import synthientpy as synthient

async def check_ip_risk(ip_address: str):
    client = synthient.AsyncClient(api_key="sk_your_api_key")

    response = await client.lookup_ip(ip_address)

    print(f"IP: {response.ip}")
    print(f"Risk Score: {response.ip_data.ip_risk}")
    print(f"Categories: {response.ip_data.categories}")

    return response

# Run the async function
asyncio.run(check_ip_risk("8.8.8.8"))
```

--------------------------------

### Perform IP Lookup with SynthientPy (Python)

Source: https://context7.com/synthient/synthientpy/llms.txt

Shows how to query risk, geo, and behavioral information for an IP address using the synchronous client. The response object contains detailed network, location, and behavioral data.

```python
import synthientpy as synthient

client = synthient.Client(api_key="sk_your_api_key")

# Look up an IP address
response = client.lookup_ip("8.8.8.8")

# Access basic information
print(f"IP: {response.ip}")
print(f"Risk Score: {response.ip_data.ip_risk}")  # 0-100 scale

# Access network information
if response.network:
    print(f"ASN: {response.network.asn}")
    print(f"ISP: {response.network.isp}")
    print(f"Organization: {response.network.org}")
    print(f"Network Type: {response.network.type}")  # RESIDENTIAL, BUSINESS, etc.
    print(f"Domain: {response.network.domain}")

# Access location information
if response.location:
    print(f"Country: {response.location.country}")
    print(f"City: {response.location.city}")
    print(f"State: {response.location.state}")
    print(f"Timezone: {response.location.timezone}")
    print(f"Coordinates: {response.location.latitude}, {response.location.longitude}")

# Access behavioral data
print(f"Device Count: {response.ip_data.device_count}")
print(f"Behaviors: {response.ip_data.behavior}")  # ['VPN_USER', 'ACTIVE_CRAWLER', etc.]
print(f"Categories: {response.ip_data.categories}")  # ['TOR_NODE', 'FREE_VPN', etc.]

# Access device information
for device in response.ip_data.devices:
    print(f"Device OS: {device.os} {device.version}")

# Access enriched data from third-party providers
if response.ip_data.enriched:
    for entry in response.ip_data.enriched:
        print(f"Provider: {entry.provider}, Type: {entry.type}, Last Seen: {entry.last_seen}")
```

--------------------------------

### Deploy project updates

Source: https://github.com/synthient/synthientpy/blob/main/CONTRIBUTING.md

Commands for maintainers to increment the version and push changes to trigger a deployment.

```bash
poetry patch
git push
git push --tags
```

--------------------------------

### Lookup IP Address Information

Source: https://github.com/synthient/synthientpy/blob/main/README.md

Shows how to use the synchronous and asynchronous clients to look up information about a given IP address.

```python
import synthientpy as synthient

client = synthient.Client(api_key="sk_...")

ip_info = client.lookup_ip("8.8.8.8")
print(ip_info.ip_data.ip_risk)
print(ip_info.location)
print(ip_info.network)
```

```python
import asyncio
import synthientpy as synthient

async def main():
    client = synthient.AsyncClient(api_key="sk_...")

    ip_info = await client.lookup_ip("8.8.8.8")
    print(ip_info.ip_data.ip_risk)

asyncio.run(main())
```

--------------------------------

### Feed Format and Sort Order Options (Python)

Source: https://context7.com/synthient/synthientpy/llms.txt

Illustrates the usage of `synthient.FeedFormat` and `synthient.SortOrder` enums for configuring data retrieval. Shows how to specify CSV, JSONL, or TEXT formats, and ASC or DESC sorting orders when fetching anonymizer data.

```python
import synthientpy as synthient

# Available formats
synthient.FeedFormat.CSV    # Comma-separated values
synthient.FeedFormat.JSONL  # JSON Lines (one JSON object per line)
synthient.FeedFormat.TEXT   # Plain text, one IP per line with provider annotation

# Sort order options
synthient.SortOrder.ASC   # Ascending order
synthient.SortOrder.DESC  # Descending order (default)

# Example: Get data in all formats
client = synthient.Client(api_key="sk_your_api_key")

csv_data = client.anonymizers(format=synthient.FeedFormat.CSV)
jsonl_data = client.anonymizers(format=synthient.FeedFormat.JSONL)
text_data = client.anonymizers(format=synthient.FeedFormat.TEXT)
```

--------------------------------

### Run project tests

Source: https://github.com/synthient/synthientpy/blob/main/CONTRIBUTING.md

Commands to execute the full test suite using tox or a specific subset using pytest.

```bash
tox
pytest tests.test_synthientpy
```

--------------------------------

### Async Credits Check

Source: https://context7.com/synthient/synthientpy/llms.txt

Asynchronously retrieve credit balance information.

```APIDOC
## Async Credits Check

Asynchronously retrieve credit balance information.

### Method
GET

### Endpoint
`/v1/account/credits`

### Request Example

```python
import asyncio
import synthientpy as synthient

async def check_credits():
    client = synthient.AsyncClient(api_key="sk_your_api_key")
    credits_info = await client.credits()
    print(credits_info)

asyncio.run(check_credits())
```
```

--------------------------------

### Retrieve Data Feeds (Anonymizers and Blacklist)

Source: https://github.com/synthient/synthientpy/blob/main/README.md

Demonstrates how to fetch anonymizer and blacklist data feeds using the synchronous client, specifying parameters like provider, type, format, and country code.

```python
import synthientpy as synthient

client = synthient.Client(api_key="sk_...")

anonymizers = client.anonymizers(
    provider="BIRDPROXIES",
    type="RESIDENTIAL_PROXY",
    last_observed="7D",
    format=synthient.FeedFormat.CSV,
    country_code="US",
)

blacklist = client.blacklist(
    provider="NORDVPN",
    type="COMMERCIAL_VPN",
    format=synthient.FeedFormat.CSV,
)
```

--------------------------------

### Asynchronous Data Feed Retrieval (Python)

Source: https://context7.com/synthient/synthientpy/llms.txt

Fetches anonymizer and blacklist data asynchronously using `synthient.AsyncClient`. This is suitable for high-throughput applications where concurrent data fetching is required. The function returns both anonymizer and blacklist data.

```python
import asyncio
import synthientpy as synthient

async def fetch_feeds():
    client = synthient.AsyncClient(api_key="sk_your_api_key")

    # Fetch anonymizers asynchronously
    anonymizers = await client.anonymizers(
        format=synthient.FeedFormat.CSV,
        last_observed="7D",
        country_code="DE"
    )

    # Fetch blacklist asynchronously
    blacklist = await client.blacklist(
        format=synthient.FeedFormat.JSONL,
        type="TOR_NODE"
    )

    return anonymizers, blacklist

# Run async feeds fetch
anon_data, blacklist_data = asyncio.run(fetch_feeds())
```

--------------------------------

### Fetch Blacklist Data with Filters (Python)

Source: https://context7.com/synthient/synthientpy/llms.txt

Retrieves blacklist data, including IPs and subnets from proxy providers, VPNs, and TOR nodes. Supports filtering by provider and type, and outputting in CSV or TEXT format. The data can be saved to files for use in firewalls or parsed into IP lists.

```python
import synthientpy as synthient

client = synthient.Client(api_key="sk_your_api_key")

# Get blacklist data filtered by provider and type
blacklist_csv = client.blacklist(
    provider="NORDVPN",               # Filter by VPN/proxy provider
    type="COMMERCIAL_VPN",            # Filter by service type
    format=synthient.FeedFormat.CSV,  # Output format
    order=synthient.SortOrder.DESC    # Sort order
)

# Save to file for firewall integration
with open("blacklist.csv", "wb") as f:
    f.write(blacklist_csv)

# Get full blacklist in text format
blacklist_text = client.blacklist(
    format=synthient.FeedFormat.TEXT
)

# Parse as IP list
ip_list = blacklist_text.decode("utf-8").strip().split("\n")
print(f"Total IPs in blacklist: {len(ip_list)}")
for ip in ip_list[:10]:  # Print first 10
    print(ip)
```

--------------------------------

### Fetch Anonymizers Feed (Python)

Source: https://context7.com/synthient/synthientpy/llms.txt

Illustrates fetching bulk data containing historical proxy and anonymizer information using the synchronous client. Supports filtering by provider, type, recency, and country code, returning data in various formats like CSV, JSONL, or TEXT.

```python
import synthientpy as synthient

client = synthient.Client(api_key="sk_your_api_key")

# Example usage for fetching anonymizers feed would go here, 
# but the provided text is incomplete for this snippet.
```

--------------------------------

### Credits Check

Source: https://context7.com/synthient/synthientpy/llms.txt

Retrieve the current credit balance for your authenticated account.

```APIDOC
## Credits Check

Retrieve the current credit balance for your authenticated account.

### Method
GET

### Endpoint
`/v1/account/credits`

### Response
#### Success Response (200)
- **credits** (integer) - Total credits available.
- **used** (integer) - Credits used.
- **remaining** (integer) - Credits remaining.

### Request Example

```python
import synthientpy as synthient

client = synthient.Client(api_key="sk_your_api_key")
credits_info = client.credits()
print(credits_info)
```

### Response Example

```json
{
  "credits": 10000,
  "used": 500,
  "remaining": 9500
}
```
```

--------------------------------

### Async IP Lookup

Source: https://context7.com/synthient/synthientpy/llms.txt

Perform asynchronous IP lookups for non-blocking operations in async applications.

```APIDOC
## Async IP Lookup

Perform asynchronous IP lookups for non-blocking operations in async applications.

### Method
GET

### Endpoint
`/v1/ip/lookup/{ip_address}`

### Parameters
#### Path Parameters
- **ip_address** (string) - Required - The IP address to look up.

### Request Example

```python
import asyncio
import synthientpy as synthient

async def check_ip_risk(ip_address: str):
    client = synthient.AsyncClient(api_key="sk_your_api_key")
    response = await client.lookup_ip(ip_address)
    print(f"IP: {response.ip}")
    print(f"Risk Score: {response.ip_data.ip_risk}")
    print(f"Categories: {response.ip_data.categories}")
    return response

asyncio.run(check_ip_risk("8.8.8.8"))
```
```

--------------------------------

### Fetch Anonymizers with Filters (Python)

Source: https://context7.com/synthient/synthientpy/llms.txt

Retrieves anonymizer data using various filters like provider, type, recency, country code, and output format. The CSV output can be written directly to a file. JSONL format allows for line-by-line processing, and TEXT format provides a simple list of IPs.

```python
import synthientpy as synthient

client = synthient.Client(api_key="sk_your_api_key")

# Get anonymizers with various filters
anonymizers_csv = client.anonymizers(
    provider="BIRDPROXIES",           # Filter by provider name
    type="RESIDENTIAL_PROXY",          # Filter by service type
    last_observed="7D",                # Recency: 24H, 7D, 30D, 1M, etc.
    format=synthient.FeedFormat.CSV,   # Output format: CSV, JSONL, TEXT
    country_code="US",                 # Filter by country code
    full=False,                        # True to return all records
    order=synthient.SortOrder.DESC     # Sort order: ASC or DESC
)

# Write CSV data to file
with open("anonymizers.csv", "wb") as f:
    f.write(anonymizers_csv)

# Get anonymizers in JSONL format for processing
anonymizers_jsonl = client.anonymizers(
    format=synthient.FeedFormat.JSONL,
    last_observed="24H"
)

# Process JSONL data line by line
import json
for line in anonymizers_jsonl.decode("utf-8").strip().split("\n"):
    if line:
        record = json.loads(line)
        print(record)

# Get simple text format (one IP per line)
anonymizers_text = client.anonymizers(
    format=synthient.FeedFormat.TEXT,
    type="COMMERCIAL_VPN"
)
print(anonymizers_text.decode("utf-8"))
```

--------------------------------

### IP Lookup

Source: https://context7.com/synthient/synthientpy/llms.txt

Query risk, geo, and behavioral information for any IP address. Returns an `IPLookupResponse` object containing network details, location data, and risk assessment.

```APIDOC
## IP Lookup

Query risk, geo, and behavioral information for any IP address. Returns an `IPLookupResponse` object containing network details, location data, and risk assessment.

### Method
GET

### Endpoint
`/v1/ip/lookup/{ip_address}`

### Parameters
#### Path Parameters
- **ip_address** (string) - Required - The IP address to look up.

#### Query Parameters
- **provider** (string) - Optional - Specify a data provider (e.g., 'maxmind', 'ipinfo').
- **fields** (string) - Optional - Comma-separated list of fields to include in the response (e.g., 'network,location,ip_data').

### Request Example

```python
import synthientpy as synthient

client = synthient.Client(api_key="sk_your_api_key")
response = client.lookup_ip("8.8.8.8")

print(f"IP: {response.ip}")
print(f"Risk Score: {response.ip_data.ip_risk}")
```

### Response
#### Success Response (200)
- **ip** (string) - The queried IP address.
- **network** (object) - Network information (ASN, ISP, Organization, Type, Domain).
- **location** (object) - Geolocation data (Country, City, State, Timezone, Latitude, Longitude).
- **ip_data** (object) - Comprehensive IP data including risk score, behaviors, categories, device information, and enriched data.

#### Response Example

```json
{
  "ip": "8.8.8.8",
  "network": {
    "asn": 15169,
    "isp": "Google LLC",
    "org": "Google LLC",
    "type": "BUSINESS",
    "domain": "google.com"
  },
  "location": {
    "country": "US",
    "city": "Mountain View",
    "state": "California",
    "timezone": "America/Los_Angeles",
    "latitude": 37.4056,
    "longitude": -122.0775
  },
  "ip_data": {
    "ip_risk": 10,
    "device_count": 5,
    "behavior": ["ACTIVE_CRAWLER"],
    "categories": ["GOOGLE_DNS"],
    "devices": [
      {
        "os": "Linux",
        "version": "Unknown"
      }
    ],
    "enriched": [
      {
        "provider": "some_provider",
        "type": "some_type",
        "last_seen": "2023-10-27T10:00:00Z"
      }
    ]
  }
}
```
```

--------------------------------

### Anonymizers Feed

Source: https://context7.com/synthient/synthientpy/llms.txt

Fetch bulk data containing historical proxy and anonymizer information. Supports filtering by provider, type, recency, and country code. Returns raw bytes in CSV, JSONL, or TEXT format.

```APIDOC
## Anonymizers Feed

Fetch bulk data containing historical proxy and anonymizer information. Supports filtering by provider, type, recency, and country code. Returns raw bytes in CSV, JSONL, or TEXT format.

### Method
GET

### Endpoint
`/v1/feeds/anonymizers`

### Parameters
#### Query Parameters
- **provider** (string) - Optional - Filter by provider (e.g., 'sshunnel', 'oxylabs').
- **type** (string) - Optional - Filter by type (e.g., 'residential', 'datacenter').
- **recency** (string) - Optional - Filter by recency (e.g., '1h', '24h').
- **country** (string) - Optional - Filter by 2-letter country code (e.g., 'US', 'GB').
- **format** (string) - Optional - Output format ('csv', 'jsonl', 'text'). Defaults to 'csv'.

### Request Example

```python
import synthientpy as synthient

client = synthient.Client(api_key="sk_your_api_key")

# Fetch anonymizer data for the last 24 hours in JSONL format
response_bytes = client.get_anonymizers_feed(
    recency="24h",
    format="jsonl"
)

# Process the response (e.g., decode and parse)
print(response_bytes.decode('utf-8'))
```
```
Tokens:
Raw