# DataSea Developer Docs

DataSea provides customer-facing residential proxy access and account API workflows.

Canonical docs: https://developers.datasea.io/docs
OpenAPI spec: https://developers.datasea.io/openapi.yaml
Customer API base URL: https://api.datasea.io
Dashboard: https://app.datasea.io/dashboard
Residential proxy dashboard: open Proxies > Residential in the DataSea dashboard.

## Current public proxy product

Residential proxies are live.

Residential proxy host: pr.datasea.io
Recommended HTTP forward proxy URL: http://pr.datasea.io:7011
HTTPS forward proxy URL: https://pr.datasea.io:7010
SOCKS5 URL: socks5h://pr.datasea.io:7012
SOCKS5 over TLS URL: socks5h://pr.datasea.io:7013
Gateway helper URL: https://pr.datasea.io/gateway

Mobile, ISP, and Datacenter proxies are coming soon. Do not use pm.datasea.io, pi.datasea.io, or pd.datasea.io in integrations today.

## Proxy authentication

DataSea proxy traffic uses Basic authentication with a proxy username and proxy password from the dashboard.

Country targeting is added to the username. The dashboard formats United States as:

<proxyUser>_country-UnitedStates

Sticky sessions use `_session` or `_sessid`:

<proxyUser>_country-UnitedStates_session-demo

State, city, and ZIP targeting are not supported today.

## Minimal cURL residential proxy example

```bash
curl -x "http://pr.datasea.io:7011" \
  -U "<proxyUser>_country-UnitedStates_session-demo:<proxyPassword>" \
  https://httpbin.org/ip
```

## Minimal Python requests example

```python
import requests

proxy_user = "<proxyUser>_country-UnitedStates_session-demo"
proxy_pass = "<proxyPassword>"
proxy_url = f"http://{proxy_user}:{proxy_pass}@pr.datasea.io:7011"

proxies = {"http": proxy_url, "https": proxy_url}
response = requests.get("https://httpbin.org/ip", proxies=proxies, timeout=30)
response.raise_for_status()
print(response.json())
```

## Customer API authentication

The documented DataSea customer API uses bearer tokens returned by `/login` or OAuth exchange.

```bash
curl -X POST https://api.datasea.io/login \
  -H "Content-Type: application/json" \
  -d '{"username":"<accountUsername>","password":"<accountPassword>"}'

curl https://api.datasea.io/whoami \
  -H "Authorization: Bearer <token>"
```

API keys are account-managed credentials but are not the documented auth method for public API requests until API-key request auth is enabled. API keys are not proxy credentials.