How to Use Geonode Proxies with cURL

Why start with cURL

cURL is the fastest way to confirm that a Geonode endpoint works before you write any code, and the best tool for isolating problems later. If a request works in cURL and fails in your scraper, the problem is in the scraper. If it fails in cURL too, it's the endpoint, the account or the target.

Get your endpoint from the Geonode dashboard in host:port:username:password format.

The basic request

curl -x "http://USERNAME:PASSWORD@HOST:PORT" https://api.ipify.org

-x (or --proxy) sets the proxy. You should see an IP that isn't yours. Run it a few times with a rotating endpoint and the IP should change.

If your password contains special characters, pass credentials separately to avoid URL-encoding issues:

curl -x "http://HOST:PORT" -U "USERNAME:PASSWORD" https://api.ipify.org

Checking location

curl -s -x "http://USERNAME-country-de:PASSWORD@HOST:PORT" https://ipapi.co/json/

The JSON shows country, region and city as one geolocation service sees them. The -country- suffix follows the pattern in Geonode's docs; use your dashboard's targeting format. Compare a few exits with a second geolocation service if location accuracy matters.

Testing sticky sessions

With a sticky endpoint, run the request several times. The IP should stay the same until the session lifetime ends:

for i in 1 2 3 4 5; do curl -s -x "http://STICKY_USER:PASSWORD@HOST:PORT" https://api.ipify.org; echo; done

SOCKS5

curl -x "socks5h://USERNAME:PASSWORD@HOST:SOCKS_PORT" https://api.ipify.org

socks5h resolves DNS through the proxy; plain socks5 resolves locally. Check the dashboard for the SOCKS port.

Debugging with verbose output

curl -v -x "http://USERNAME:PASSWORD@HOST:PORT" https://example.com -o /dev/null

Verbose output shows the connection to the proxy, the CONNECT request for HTTPS, the proxy's response and the TLS handshake with the site. Key lines:

• HTTP/1.1 407 Proxy Authentication Required: credentials or username format.
• HTTP/1.1 200 Connection established followed by a TLS handshake: the proxy is fine; any later error is from the target.
• Failed to connect to HOST port PORT: wrong host or port, or outbound traffic blocked on your network.

Timing a request

curl -s -o /dev/null -x "http://USERNAME:PASSWORD@HOST:PORT" \
  -w "connect=%{time_connect} tls=%{time_appconnect} ttfb=%{time_starttransfer} total=%{time_total}\n" \
  https://example.com/

Run it 20 to 50 times against your real target to get a rough latency picture. For proper benchmarks, see proxy speed test.

Environment variables

cURL honours http_proxy, https_proxy and all_proxy:

export https_proxy="http://USERNAME:PASSWORD@HOST:PORT"
curl https://api.ipify.org

Remember to unset them afterwards, or every later cURL command will use the proxy.

Checking a target page

curl -s --compressed -x "http://USERNAME:PASSWORD@HOST:PORT" https://www.example.com/product/123 | grep -i "price"

--compressed requests compressed content, which reduces billed bandwidth. If you get a CAPTCHA page instead of content, the target is blocking, not the proxy.

A five-step troubleshooting routine with cURL

When something in your proxy setup breaks, this routine finds the cause quickly.

1. Test the endpoint against an IP echo service. If it fails, the problem is the endpoint, credentials or your network. Check the dashboard for the exact host, port and username format, and whether your account has balance.
2. Add -v and read the proxy's response. A 407 means authentication; a connection failure means host, port or outbound firewall; "Connection established" means the proxy is working.
3. Test the real target. If the echo service works and the target fails, the target is blocking or slow. Look at the response body: a CAPTCHA or "access denied" page confirms blocking.
4. Try a different product or location. If datacenter fails on the target and residential succeeds, the target blocks hosting ranges. If a narrow city target fails and the country target works, the narrow pool may be thin at that hour.
5. Compare with your application. If cURL succeeds and your code fails with the same endpoint and target, the difference is in your code: headers, connection reuse, authentication handling or TLS behaviour.

Keep the commands that worked in a small text file or shell script in your repository. When a teammate reports a proxy problem, running that script tells you in seconds whether the issue is the proxy, the target or the code.

Useful cURL options for proxy work

These options cover nearly every proxy check you'll need. For broader testing methods, see how to check if a proxy works and common proxy errors.

Keeping a test script

Save your working commands in a small script with the endpoint values read from environment variables. When anyone on the team suspects a proxy problem, running it gives an answer in seconds and a shared starting point for debugging.

FAQ

How do I know the proxy is working?

Request an IP echo service through it and confirm the IP isn't yours.

Why do I get 407 errors?

Wrong username, password or targeting format. Copy credentials from the dashboard, and pass them with -U if they contain special characters.

What's the difference between socks5 and socks5h?

socks5h sends hostnames to the proxy for DNS resolution, which avoids DNS leaks.

Can cURL rotate IPs?

With a rotating endpoint, each new connection gets a new exit, so separate cURL invocations get different IPs.