Build a Rotating Proxy Connection - Floppydata Client API

Use this endpoint when a customer needs one usable rotating proxy connection string.

Subusers are optional. Omit subuserId to use your account’s default proxy credentials. Set it only when you want to organize proxy traffic into groups for separate reporting or replace exposed credentials. See Manage Rotating Proxy Subusers.

1. Choose a Location

curl --request GET \
  --url "$FLOPPY_BASE_URL/v2/proxy/rotating/locations?type=residential" \
  --header "X-Api-Key: $FLOPPY_API_KEY"

The response lists countries with country-level cities and states. It is not a city-under-state mapping.

2. Build the Connection

curl --request POST \
  --url "$FLOPPY_BASE_URL/v2/proxy/rotating/connections" \
  --header "Content-Type: application/json" \
  --header "X-Api-Key: $FLOPPY_API_KEY" \
  --data '{
    "type": "residential",
    "country": "US",
    "city": "New York",
    "protocol": "socks5",
    "rotation": 15,
    "udp": true
  }'

Copy connection.connectionString from the response.

{
  "connection": {
    "protocol": "socks5",
    "host": "geo.g-w.info",
    "port": 10800,
    "username": "user-USERNAME-type-residential-country-US-city-New_York-rotation-15-udp-1",
    "password": "PASSWORD",
    "connectionString": "socks5://user-USERNAME-type-residential-country-US-city-New_York-rotation-15-udp-1:PASSWORD@geo.g-w.info:10800"
  },
  "parameters": {
    "type": "residential",
    "country": "US",
    "city": "New York",
    "rotation": 15,
    "protocol": "socks5",
    "udp": true
  }
}

Request Rules

Field	Notes
`subuserId`	Optional. ID from `GET /v2/proxy/rotating/subusers`. Omit it to use the account’s default proxy credentials.
`type`	`residential`, `mobile`, or `datacenter`.
`country`	Two-letter country code.
`state`	Optional. Takes precedence over `city` when both are supplied.
`city`	Optional. Used when `state` is not supplied.
`rotation`	`-1` for every request, `0` for sticky session, or `1..60` minutes.
`protocol`	`http`, `https`, or `socks5`.
`udp`	Optional. Use `true` only with `protocol: "socks5"` and `type: "residential"` or `"mobile"`. Adds `udp-1` to the proxy username.

3. Use the Connection

curl --proxy "socks5://USERNAME:PASSWORD@geo.g-w.info:10800" \
  "https://example.com"

Usage Tips

Situation	Tip
You want one ready-to-use proxy URL	Copy `connection.connectionString`; it already includes protocol, username, password, host, and port.
You need country targeting	Send `country` as a two-letter code such as `US`.
You need regional targeting	Use `state` or `city`; if both are supplied, `state` takes precedence.
You want a new IP often	Use `rotation: -1` for rotation on every request.
You want a sticky session	Use `rotation: 0`.
You want timed rotation	Use `rotation` from `1` to `60` minutes.
You need UDP traffic	Use `protocol: "socks5"` with residential or mobile proxies and set `udp: true`.
You are unsure about proxy type	Start with `residential`; use `mobile` or `datacenter` only when that matches the target workflow.

Generate one connection per call. If your app needs several proxy URLs, call the connections endpoint several times and store each returned connection.connectionString.

Run connections in API Reference

Generate a live connection string from the docs.

Manage subusers

Organize proxy groups or replace exposed credentials.

Check the proxy

Validate the connection string returned by the API.

​1. Choose a Location

​2. Build the Connection

​Request Rules

​3. Use the Connection

​Usage Tips

Run connections in API Reference

Manage subusers

Check the proxy

1. Choose a Location

2. Build the Connection

Request Rules

3. Use the Connection

Usage Tips