Real Location Screenshots endpoints | PagePixels Screenshot API

Real Location Screenshots

Create a screenshot from a specific geographical location using the snap endpoint with the real_location parameter.

This ensures that the requested screenshot is taken from a server located within the geographical region of your choice.

Learn more about geolocation screenshots and check out the geolocation screenshot web tutorial.

Option	Expected Value
url	The URL of the webpage for which you want a screenshot.
access_token	Your account's Private API Key.
real_location	The location from which to take the screenshot. Must be one of the values returned by the real_locations endpoint.
custom_proxy_id	Optional. The id of a proxy stored on your account, to route the capture through your own proxy instead of the PagePixels network. No Real Location bandwidth is used. Requires the Bring Your Own Proxy addon. See Bring Your Own Proxy.

This Real Location example uses the Mars Rover Perseverance's Wikipedia page with the real_location set to "USA":

GET REQUEST /snap http

https://api.pagepixels.com/snap?url=https://en.wikipedia.org/wiki/Perseverance_(rover)&real_location=USA&access_token=your-api-key

In this example, the real_location is set to "USA", so the screenshot will be taken from a randomly selected city within the United States. You can replace "USA" with any valid location returned by the real_locations endpoint.

Upgradeable Feature: Free and paid plans receive 32MB of free Real Location bandwidth each month. Paid accounts can purchase additional bandwidth at $20.00/month per 2GB of bandwidth.

Prefer your own proxy? With the Bring Your Own Proxy addon you can route captures through any HTTP or HTTPS proxy you control, with no bandwidth limits. See Bring Your Own Proxy.

List All Real Locations

GET /real_locations

Use the get real_locations endpoint to return an array of locations you can pass to the real_location parameter. Returned locations are sorted alphabetically in ascending order.

Example

GET REQUEST /real_locations http

https://api.pagepixels.com/real_locations?access_token=your-api-key

JSON RESPONSE

{
  "success": true,
  "results": ["Afghanistan", "Alabama", "Alaska", "Albania", "Andorra", "Angola", "Argentina", "Arizona", "Arkansas", "Armenia", "Aruba", "Australia", "Austria", "Azerbaijan", "Bahamas", "Bahrain", "Bangladesh", "Belarus", "Belgium", "Belize", "Benin", "Berlin", "Bhutan", "Bolivia", "Bosnia and Herzegovina", "Brazil", "British Virgin Islands", "Bulgaria", "California", "Cambodia", "Cameroon", "Canada", "Chad", "Chicago", "Chile", "China", "Colombia", "Colorado", "Connecticut", "Costa Rica", "Côte d'Ivoire", "Croatia", "Cuba", "Cyprus", "Czech Republic", "Delaware", "Denmark", "Djibouti", "Dominica", "Ecuador", "Egypt", "Estonia", "Ethiopia", "Europe", "Europe", "Fiji", "Finland", "Florida", "France", "Gambia", "Georgia", "Georgia (US)", "Germany", "Germany", "Ghana", "Great Britain", "Greece", "Haiti", "Hawaii", "Honduras", "Hong Kong", "Houston", "Hungary", "Iceland", "Idaho", "Illinois", "India", "Indiana", "Indonesia", "Iowa", "Iran", "Iraq", "Ireland", "Israel", "Italy", "Jamaica", "Japan", "Jordan", "Kansas", "Kazakhstan", "Kentucky", "Kenya", "Latvia", "Lebanon", "Liberia", "Liechtenstein", "Lithuania", "London", "Los Angeles", "Louisiana", "Luxembourg", "Macedonia", "Madagascar", "Maine", "Malaysia", "Maldives", "Mali", "Malta", "Maryland", "Massachusetts", "Mauritania", "Mauritius", "Mexico", "Miami", "Michigan", "Minnesota", "Mississippi", "Missouri", "Moldova", "Monaco", "Mongolia", "Montana", "Montenegro", "Morocco", "Moscow", "Mozambique", "Myanmar", "Nebraska", "Netherlands", "Netherlands", "Nevada", "New Hampshire", "New Jersey", "New Mexico", "New York", "New York", "New Zealand", "Nigeria", "North Carolina", "North Dakota", "Norway", "Ohio", "Oklahoma", "Oman", "Oregon", "Pakistan", "Panama", "Paraguay", "Pennsylvania", "Peru", "Philippines", "Poland", "Portugal", "Puerto Rico", "Qatar", "Rhode Island", "Romania", "Romania", "Russia", "Saudi Arabia", "Senegal", "Serbia", "Seychelles", "Singapore", "Slovakia", "Slovenia", "South Africa", "South Carolina", "South Dakota", "South Korea", "South Sudan", "Spain", "Sudan", "Sweden", "Switzerland", "Syria", "Taiwan", "Tennessee", "Texas", "Thailand", "Togo", "Trinidad and Tobago", "Tunisia", "Turkey", "Turkmenistan", "UAE", "Uganda", "Ukraine", "United Kingdom", "Uruguay", "US", "USA", "Utah", "Uzbekistan", "Vermont", "Vietnam", "Virginia", "Washington", "West Virginia", "Wisconsin", "Wyoming", "Yemen", "Zambia", "Zimbabwe"]
}

Response Breakdown

Key	Description
success	A boolean indicating whether the request was successful.
results	An array of locations sorted alphabetically in ascending order.

Bring Your Own Proxy

With the Bring Your Own Proxy addon, captures can go through a proxy you control instead of the PagePixels network: any HTTP or HTTPS proxy, in any location your provider offers, including static IPs for allow-listed or internal sites. Traffic is billed by your proxy provider, so your Real Location bandwidth is never used and there is no bandwidth limit.

How it works

1. Store the proxy once with the store proxy endpoint. We run a quick connection test through it, keep the password encrypted, and return an id.

2. Add custom_proxy_id to any snap or scheduled screenshot. That is all. Proxy credentials are never accepted on those requests, and custom_proxy_id takes the place of real_location when both are given.

The addon is available on any paid screenshot plan. If you are on the free plan, pick a plan first and then add the addon. Requests that need the addon return a clear error_code with the upgrade path, before any screenshot is taken.

This example takes a screenshot through a stored proxy:

GET REQUEST /snap bash

curl -X GET "https://api.pagepixels.com/snap" \
  --data-urlencode "url=https://en.wikipedia.org/wiki/Perseverance_(rover)" \
  -d custom_proxy_id=42 \
  -d json=true \
  -d access_token="your-api-key"

JSON RESPONSE

{
  "id": "id",
  "embed_url": "https://pagepixels.com/app/screenshots/:screenshot_configuration_id/embed",
  "screenshot_configuration_id": "screenshot_configuration_id",
  "direct_link": "https://cdn.pagepixels.com/.../c6df60d2d89b2c-1734222361743.jpg",
  "direct_thumbnail_link": "https://cdn.pagepixels.com/.../thumb_c6df60d2d89b2c-1734222361743.jpg",
  "taken_at_timestamp": "1734222368651",
  "taken_at": "2024-12-15T00:26:08+00:00",
  "is_proxy_screenshot": false,
  "proxy_server": null,
  "custom_proxy": "proxy.example.com:8080",
  "job_id": "job_id"
}

The response gains custom_proxy (the stored proxy's host and port) whenever a capture went through your own proxy. is_proxy_screenshot stays false for these, because they do not use Real Location bandwidth. Everything else is unchanged.

Store or Test a Proxy

PUT /proxies

Use the put proxies endpoint to store a proxy, or to update one by passing its id. Unless test=false, we fetch a small test page through it before answering, so you know it accepts connections and credentials. Leave password out on an update to keep the stored one. This is the only endpoint that ever receives a proxy password, and it never appears in a response.

Key	Expected Value
id	Optional. The id of a stored proxy to update.
protocol	`http` (default) or `https`.
host	Hostname or IPv4 address. Required.
port	1 to 65535. Defaults to 8080, 443 or 1080 by protocol.
username	Optional. Requires a password.
password	Optional. Stored encrypted.
test	Optional. `false` skips the connection test.

Example

PUT REQUEST /proxies bash

curl -X PUT "https://api.pagepixels.com/proxies" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "http",
    "host": "proxy.example.com",
    "port": 8080,
    "username": "pagepixels",
    "password": "…"
  }'

JSON RESPONSE

{
  "success": true,
  "proxy": {
    "id": 42,
    "label": "proxy.example.com:8080",
    "protocol": "http",
    "host": "proxy.example.com",
    "port": 8080,
    "username": "pagepixels",
    "has_password": true,
    "display_url": "http://pagepixels:••••••@proxy.example.com:8080",
    "verified": true,
    "verified_at": "2026-09-05T02:10:31Z",
    "exit_ip": "203.0.113.42",
    "last_test_ms": 412,
    "last_error": null
  },
  "result": {"exit_ip": "203.0.113.42", "ms": 412}
}

If the test fails you get a 400 with a specific code (proxy_auth_failed, proxy_connection_failed, proxy_host_not_found, proxy_timeout) and the proxy is stored but marked unverified, so you can fix the settings and test again.

List Your Proxies

GET /proxies

Use the get proxies endpoint to list your stored proxies with their ids, last test result, and your addon status.

Example

GET REQUEST /proxies bash

curl -X GET "https://api.pagepixels.com/proxies" \
  -H "Authorization: Bearer your-api-key"

JSON RESPONSE

{
  "success": true,
  "bring_your_own_proxy_enabled": true,
  "has_paid_plan": true,
  "proxies": [
    {"id": 42, "label": "proxy.example.com:8080", "protocol": "http", "host": "proxy.example.com", "port": 8080, "username": "pagepixels", "has_password": true, "verified": true, "exit_ip": "203.0.113.42", "last_test_ms": 412, "last_error": null}
  ]
}

Test a Proxy

POST /proxies/:id/test

Use the post proxies/:id/test endpoint to re-run the connection test for a stored proxy, for example after rotating its password or allow-listing our IPs.

Example

POST REQUEST /proxies/42/test bash

curl -X POST "https://api.pagepixels.com/proxies/42/test" \
  -H "Authorization: Bearer your-api-key"

JSON RESPONSE

{
  "success": true,
  "proxy": {"id": 42, "label": "proxy.example.com:8080", "verified": true, "exit_ip": "203.0.113.42", "last_test_ms": 398},
  "result": {"exit_ip": "203.0.113.42", "ms": 398}
}

Remove a Proxy

DELETE /proxies/:id

Use the delete proxies/:id endpoint to remove a stored proxy. Screenshot configurations that reference it fail with custom_proxy_not_found on their next capture until they are updated, and nothing falls back to the PagePixels network without you asking.

Example

DELETE REQUEST /proxies/42 bash

curl -X DELETE "https://api.pagepixels.com/proxies/42" \
  -H "Authorization: Bearer your-api-key"

JSON RESPONSE

{
  "success": true,
  "note": "Proxy proxy.example.com:8080 was removed. Screenshot configurations using it will fail with custom_proxy_not_found until they are updated."
}

Bring Your Own Proxy Errors

These codes are returned with success: false and a note that explains what to do. They are checked before any screenshot is taken.

error_code	Meaning
byo_proxy_plan_required (402)	Bring Your Own Proxy is an addon for paid screenshot plans. Pick a plan first, then add the addon.
byo_proxy_addon_required (402)	Your plan is active but the Bring Your Own Proxy addon is not. Add it from Plans and Addons.
custom_proxy_not_found (412)	No stored proxy matches `custom_proxy_id`. Store one with the store proxy endpoint.
invalid_proxy (400)	The proxy settings are invalid. The note names the problem.
proxy_auth_failed (400)	The proxy rejected the credentials (407). Check the username and password.
proxy_connection_failed (400)	Could not connect through the proxy. Check the host, port and protocol.
proxy_host_not_found (400)	The proxy hostname could not be resolved.
proxy_timeout (400)	The proxy did not respond in time. Check that it accepts connections from the internet.

Support

Questions? Contact us anytime by email:

support-tickets@pagepixels.com

Or send us a message through our Support page.

Real Location Screenshots