> ## Documentation Index
> Fetch the complete documentation index at: https://floppydata.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Proxy Basics

Learn how to use Floppydata proxies to route your requests through residential, mobile, or datacenter IPs with precise control.

## How it works

When you connect through Floppydata, you describe how your request should behave — and Floppydata handles routing automatically.

<CardGroup cols={2}>
  <Card title="Traditional approach" icon="list-check">
    * Manual proxy selection
    * Rotation management
    * Proxy list maintenance
  </Card>

  <Card title="Floppydata approach" icon="wand-magic-sparkles">
    * Describe the request
    * Automatic routing
    * Infrastructure abstraction
  </Card>
</CardGroup>

**You don't choose proxies manually. You describe how your request should behave – Floppydata handles the routing automatically.**

## The gateway

Your application always connects to a single proxy endpoint:

```text theme={null}
geo.g-w.info
```

You don't switch hosts for different countries or proxy types. All routing is controlled by **Smart Parameters** in the username.

### Available ports

| Port    | Protocol | Use case                       |
| ------- | -------- | ------------------------------ |
| `10080` | HTTP     | Default, works with most tools |
| `10443` | HTTPS    | Secure HTTP connection         |
| `10800` | SOCKS5   | Advanced use, automation tools |

<Tip>
  Not sure which port? Start with **10080** (HTTP)
</Tip>

## Connection format

```text theme={null}
http://USERNAME:PASSWORD@geo.g-w.info:PORT
```

**Example:**

```text theme={null}
http://user123-type-residential-country-US:yourpassword@geo.g-w.info:10080
```

The magic happens in the username — Smart Parameters control where and how your request is routed.

## What the target website sees

<Tabs>
  <Tab title="Without proxy">
    When you send requests directly, the target website sees your real IP address.

    ```text theme={null}
    Your App → Target Website
    (sees your real IP: 203.0.113.45)
    ```
  </Tab>

  <Tab title="With Floppydata">
    When you send requests through Floppydata, the target sees the **proxy exit IP** instead. Your real IP stays hidden.

    ```text theme={null}
    Your App → Floppydata → Target Website
    (sees proxy IP: 123.45.67.89 from US)
    ```

    This is what makes geo-targeting, rotation, and session control possible.
  </Tab>
</Tabs>

## Proxy types

Smart Parameters support **three rotating proxy types**:

* `residential`
* `mobile`
* `datacenter`

Static proxies are a separate product. For static proxies, use the credentials returned by the [Static Proxy API](/docs/api-reference/v2/endpoint/static-proxies) instead of adding a Smart Parameter type.

<AccordionGroup>
  <Accordion title="Residential" icon="house">
    Real user IPs with high trust level

    **Characteristics:**

    * 🔹 Rotating IPs from shared pool
    * 🔹 High trust level
    * 🔹 Medium speed
    * 🔹 Billed per GB

    **Best for:** Web scraping, SEO tracking, geo-targeting, price monitoring

    **Pricing:** \$5/GB
  </Accordion>

  <Accordion title="Mobile (4G/5G)" icon="mobile">
    Mobile carrier IPs with highest trust level

    **Characteristics:**

    * 🔹 Rotating IPs from mobile networks
    * 🔹 Very high trust level
    * 🔹 Medium speed
    * 🔹 Billed per GB

    **Best for:** Social media automation, high-risk targets, account creation, sneaker bots

    **Pricing:** \$15/GB
  </Accordion>

  <Accordion title="Datacenter" icon="server">
    Fast and cost-efficient IPs for scale

    **Characteristics:**

    * 🔹 Rotating IPs from datacenters
    * 🔹 Low trust level
    * 🔹 Fast speed
    * 🔹 Billed per GB

    **Best for:** High-volume scraping, simple sites, speed-critical tasks

    **Pricing:** \$0,6/GB
  </Accordion>
</AccordionGroup>

### Static IPs

<AccordionGroup>
  <Accordion title="ISP Static" icon="tower-cell">
    Fixed residential IP for account stability

    **Characteristics:**

    * 🔹 Fixed IP assigned to you
    * 🔹 High trust level
    * 🔹 Fast speed
    * 🔹 Billed per IP/month

    **Best for:** Account management, long sessions, multi-accounting, e-commerce accounts

    **Pricing:** \$5/IP/month
  </Accordion>

  <Accordion title="Datacenter Static" icon="hard-drive">
    Fixed datacenter IP for infrastructure

    **Characteristics:**

    * 🔹 Fixed IP assigned to you
    * 🔹 Medium trust level
    * 🔹 Fast speed
    * 🔹 Billed per IP/month

    **Best for:** Automation tools, API access, IP whitelisting

    **Pricing:** \$1/IP/month
  </Accordion>
</AccordionGroup>

## How to choose proxy type

| Use case                   | Recommended proxy       | Why                                |
| -------------------------- | ----------------------- | ---------------------------------- |
| Social media accounts      | Mobile or Static ISP    | High trust + stable identity       |
| Ad accounts (Meta, Google) | Static ISP or Mobile    | Geo-consistency required           |
| E-commerce (Amazon, eBay)  | Static ISP              | Fixed IP avoids account linking    |
| Payment platforms          | Static ISP              | IP changes trigger security checks |
| Account creation           | Mobile                  | Mobile IPs have highest trust      |
| SEO & SERP tracking        | Residential             | Accurate geo-targeting             |
| Price monitoring           | Residential             | Access localized content           |
| Web scraping (protected)   | Residential             | Higher success rate                |
| Web scraping (high volume) | Datacenter              | Faster and cheaper at scale        |
| Automation tools           | Datacenter or Static DC | Speed and performance              |
| Sneaker/ticketing bots     | Mobile or Residential   | Avoid detection systems            |

<Info>
  **General rule:**

  * Use **Rotating proxies** when you need scale and request distribution
  * Use **Static proxies** when you need a stable identity
</Info>

## Smart Parameters

Smart Parameters define how your requests are routed. They're added to the username.

### Format

```text theme={null}
USERNAME-parameter1-value1-parameter2-value2
```

### Example

```text theme={null}
user123-type-residential-country-US-city-New_York-session-abc123
```

This means:

* `type-residential` — use residential proxies
* `country-US` — route through United States
* `city-New_York` — narrow to New York
* `session-abc123` — keep same IP (sticky session)

## Available parameters

<ParamField path="type" type="string">
  Rotating proxy type to use

  **Values:**

  * `residential` — Residential
  * `mobile` — Mobile (4G/5G)
  * `datacenter` — Datacenter

  **Example:** `user123-type-mobile-country-US`
</ParamField>

<ParamField path="country" type="string">
  Exit country using ISO code

  **Examples:**

  * `country-US` — United States
  * `country-GB` — United Kingdom
  * `country-DE` — Germany

  **Example:** `user123-type-residential-country-FR`
</ParamField>

<ParamField path="city" type="string">
  Exit city (use underscores for spaces)

  **Examples:**

  * `city-New_York`
  * `city-Los_Angeles`
  * `city-London`

  **Note:** Falls back to country-level if city unavailable

  **Example:** `user123-type-residential-country-US-city-Chicago`
</ParamField>

<ParamField path="state" type="string">
  US state targeting (full name or abbreviation)

  **Examples:**

  * `state-California` or `state-CA`
  * `state-North_Carolina` or `state-NC`

  **Works with:** Residential and Mobile proxies only

  **Example:** `user123-type-residential-country-US-state-California`
</ParamField>

<ParamField path="asn" type="number">
  Target specific ISP network by Autonomous System Number

  **Example:** `user123-type-residential-country-US-asn-7018`

  **Works with:** Residential and Mobile proxies only

  **Use case:** Better compatibility with specific ISP networks
</ParamField>

<ParamField path="session" type="string">
  Sticky session ID (keeps same IP)

  **Behavior:**

  * Same session ID → same IP
  * Different session ID → different IP
  * Combine with `rotation-0` for a stable session IP

  **Lifetime:** Up to 10 minutes of inactivity

  **Example:** `user123-type-residential-country-US-session-login01`
</ParamField>

<ParamField path="rotation" type="number">
  Rotation interval in minutes

  **Values:**

  * `-1` — new IP every request
  * `0` — keep the same IP within a session
  * `1` to `60` — rotate after this many minutes

  **Example:** `user123-type-residential-country-US-rotation--1`
</ParamField>

## Sessions and rotation

### Per-request rotation

Set `rotation` to `-1` when you want a new IP for every request:

```python theme={null}
proxy_username = "user123-type-residential-country-US-rotation--1"
```

When you build this through the API, pass `rotation=-1`. In the generated username, the negative value appears as `rotation--1`.

### Sticky sessions

To keep the same IP across multiple requests, use a session:

```python theme={null}
# Same session = same IP
proxy_username = "user123-type-residential-country-US-session-checkout01"
```

**What happens:**

* All requests with the same session ID use the same IP
* Changing the session ID assigns a new IP
* `rotation-0` keeps the same IP within the session

### Session lifetime

Sessions stay active for **up to 10 minutes of inactivity**. Each request resets the timer.

```text theme={null}
12:00 → Request (IP A)
12:05 → Request (IP A) — session alive
12:14 → Request (IP A) — session alive
12:25 → Request (IP B) — session expired after 10min inactivity
```

### Interval rotation

Use a value from `1` to `60` to rotate after that many minutes:

```python theme={null}
proxy_username = "user123-type-residential-country-US-session-crawl01-rotation-15"
```

### Changing IP manually

To get a new IP before session expires, change the session value:

```python theme={null}
# Original session
"user123-type-residential-country-US-session-s01"  # → IP A
 
# New session → new IP
"user123-type-residential-country-US-session-s02"  # → IP B
```

<Info>
  There is no reset endpoint — changing the session string is how you rotate
</Info>

### Multiple sessions

Run multiple sessions simultaneously:

```python theme={null}
"user123-type-residential-country-US-session-user1"  # → IP A
"user123-type-residential-country-US-session-user2"  # → IP B
"user123-type-residential-country-US-session-user3"  # → IP C
```

Each session gets its own IP for parallel workflows.

## When to use rotation vs sessions

<Tabs>
  <Tab title="Use Rotation">
    **Use rotation when:**

    * Scraping many pages
    * Collecting large datasets
    * Avoiding rate limits
    * Distributing requests
    * No login required

    **Example:**

    ```python theme={null}
    # Scraping 1000 product pages
    proxy_username = "user123-type-residential-country-US-rotation--1"  # New IP each request
    ```
  </Tab>

  <Tab title="Use Sessions">
    **Use sessions when:**

    * Logging into accounts
    * Maintaining cookies
    * Checkout flows
    * Multi-step interactions
    * Account-based automation

    **Example:**

    ```python theme={null}
    # Login flow with multiple steps
    proxy_username = "user123-type-residential-country-US-session-login01"  # Same IP
    ```
  </Tab>
</Tabs>

## Geo targeting

Control where your requests originate from.

### Country-level targeting

```python theme={null}
proxy_username = "user123-type-residential-country-US"  # United States
proxy_username = "user123-type-residential-country-GB"  # United Kingdom
proxy_username = "user123-type-residential-country-DE"  # Germany
```

### City-level targeting

```python theme={null}
proxy_username = "user123-type-residential-country-US-city-New_York"
proxy_username = "user123-type-residential-country-US-city-Los_Angeles"
proxy_username = "user123-type-residential-country-GB-city-London"
```

<Tip>
  Use underscores instead of spaces in city names
</Tip>

### State-level targeting (US only)

```python theme={null}
proxy_username = "user123-type-residential-country-US-state-CA"  # California
proxy_username = "user123-type-residential-country-US-state-New_York"
```

### Available locations

Check available countries and cities via API:

```bash theme={null}
curl -H "X-Api-Key: YOUR_KEY" \
  "https://api.floppydata.net/v2/proxy/rotating/locations?type=residential"
```

### Fallback behavior

If a specific city is unavailable, Floppydata automatically falls back to country-level routing.

## Parameter combinations

### Common patterns

<CodeGroup>
  ```python Basic residential theme={null}
  "user123-type-residential-country-US"
  ```

  ```python With session theme={null}
  "user123-type-residential-country-US-session-login01"
  ```

  ```python City + session theme={null}
  "user123-type-residential-country-US-city-Chicago-session-user1"
  ```

  ```python Mobile proxy theme={null}
  "user123-type-mobile-country-US"
  ```

  ```python Per-request rotation theme={null}
  "user123-type-residential-country-US-rotation--1"
  ```

  ```python Datacenter proxy theme={null}
  "user123-type-datacenter-country-US"
  ```

  ```python State targeting theme={null}
  "user123-type-residential-country-US-state-California-session-s01"
  ```
</CodeGroup>

## Complete examples

### Python

```python theme={null}
import requests
 
PROXY_USER = "user123"
PROXY_PASS = "your_password"
 
# Residential, US, sticky session
proxy_username = f"{PROXY_USER}-type-residential-country-US-session-checkout01"
proxy_url = f"http://{proxy_username}:{PROXY_PASS}@geo.g-w.info:10080"
 
proxies = {
    'http': proxy_url,
    'https': proxy_url
}
 
response = requests.get('https://example.com', proxies=proxies)
print(response.text)
```

### Node.js

```javascript theme={null}
const axios = require('axios');
 
const PROXY_USER = 'user123';
const PROXY_PASS = 'your_password';
 
// Mobile, US, New York
const proxyUsername = `${PROXY_USER}-type-mobile-country-US-city-New_York`;
 
const proxy = {
    host: 'geo.g-w.info',
    port: 10080,
    auth: {
        username: proxyUsername,
        password: PROXY_PASS
    }
};
 
axios.get('https://example.com', { proxy })
    .then(res => console.log(res.data));
```

## Common questions

<AccordionGroup>
  <Accordion title="Why is my IP changing every request?" icon="question">
    Per-request rotation is enabled with `rotation--1`. To keep the same IP, add a session parameter and `rotation-0`:

    ```text theme={null}
    -session-YOUR_ID-rotation-0
    ```
  </Accordion>

  <Accordion title="Why is my IP not changing?" icon="question">
    You're using a session. To rotate:

    * Remove the session parameter
    * Change the session value
    * Or use `rotation--1`
  </Accordion>

  <Accordion title="How long do sessions last?" icon="question">
    Sessions last up to **10 minutes of inactivity**. Each request resets the timer.

    To keep a session alive longer, send periodic requests.
  </Accordion>

  <Accordion title="Can I use multiple sessions?" icon="question">
    Yes! Each unique session ID gets its own IP. Run as many parallel sessions as needed.
  </Accordion>
</AccordionGroup>