Overview#
The Proxonym API lets you manage your account from code: read balances and plans, pull usage, download proxy lists, edit the IP whitelist and manage sub-users. The Google SERP API, on its own host, returns parsed search results as JSON.
Base URL
https://api.proxonym.com/v1Paths in this reference are relative to the base URL. All requests use HTTPS. The SERP API has its own base URL, https://serp.proxonym.com/v1.
OpenAPI description
The account API is also described in OpenAPI 3.1 at /docs/api/openapi.json, ready for client generators, API tools and AI agents.
Versioning
The major version is part of the path. Breaking changes ship under a new version. Within v1, new endpoints, optional parameters and response fields can appear, so write clients that ignore fields they don't recognize.
Conventions
- Format: responses are JSON in UTF-8 with
Content-Type: application/json, except proxy lists requested withformat=txt. Send request bodies as JSON withContent-Type: application/json. - Status codes:
200on success and201when a resource is created. Failures are described in Errors. - Timestamps: ISO 8601 in UTC, for example
2026-10-01T09:30:00Z. Date parameters accept a full timestamp or a date such as2026-09-24, read as midnight UTC. - Traffic: gigabytes as decimal numbers, for example
17.836. - IDs: strings with a type prefix, such as
su_3k9x2m7qfor a sub-user. Treat them as opaque. - Missing values:
null, for example"expires_at": nullon a pack that never expires. - Products:
residential,mobile,unlimited,isp,datacenter,dedicatedandserp.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /account | Account, GB balances and active plans |
GET | /usage | Usage of one product over time |
GET | /proxies/{product} | Proxy list for datacenter, ISP or dedicated |
GET | /whitelist | List whitelisted IPs |
POST | /whitelist | Add an IP to the whitelist |
DELETE | /whitelist/{ip} | Remove an IP from the whitelist |
GET | /sub-users | List sub-users |
POST | /sub-users | Create a sub-user |
PATCH | /sub-users/{id} | Update a sub-user |
DELETE | /sub-users/{id} | Delete a sub-user |
GET | https://serp.proxonym.com/v1/search | Google results as parsed JSON |
Your first call
Create an API key in the dashboard, export it, then request your account:
export PROXONYM_API_KEY="your_api_key"
curl https://api.proxonym.com/v1/account \
-H "Authorization: Bearer $PROXONYM_API_KEY"Examples in this reference read the account API key from $PROXONYM_API_KEY and the SERP API key from $PROXONYM_SERP_KEY.
Authentication#
The account API authenticates every request with an API key, sent as a bearer token in the Authorization header:
Authorization: Bearer <API_KEY>Create and revoke keys in the dashboard. A key acts on your whole account: it can read usage, download proxy credentials and manage sub-users. A request with a missing, malformed or revoked key fails with 401:
curl -i https://api.proxonym.com/v1/account \
-H "Authorization: Bearer wrong_key"HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error": {
"code": "invalid_api_key",
"message": "The API key is missing, malformed or revoked."
}
}Keep keys secret
- Call the API from your servers only. Never ship a key in a web page, a mobile app or a public repository.
- Load keys from environment variables or a secrets manager, and keep them out of logs.
- Use a separate key for each service, so you can revoke one without touching the others.
- API keys aren't proxy credentials. Proxy connections use your proxy username and password; see proxy authentication.
Rotate keys
- Create a new key in the dashboard.
- Deploy it to every service that calls the API.
- Confirm that calls succeed with the new key, then revoke the old one.
Rotate on a schedule, and revoke a key at once if it may have leaked. Requests with a revoked key fail with 401.
SERP API key
The SERP API reads its key from the X-API-Key header instead of Authorization. See SERP API.
Rate limits#
The account API accepts 60 requests per minute. Every response tells you where you stand:
| Header | Description |
|---|---|
X-RateLimit-Limit | Requests allowed per minute: 60 |
X-RateLimit-Remaining | Requests left in the current window |
Retry-After | On 429 responses only: seconds to wait before the next request |
Over the limit, the API answers 429:
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 18
{
"error": {
"code": "rate_limited",
"message": "Rate limit of 60 requests per minute exceeded. Retry after 18 seconds."
}
}SERP API usage is metered by your plan's monthly requests instead; see SERP API.
Handling 429
Wait the number of seconds in Retry-After, then retry. To stay under the limit:
- Cache data that changes slowly, such as proxy lists and the whitelist.
- Poll usage every few minutes, not every few seconds. The finest granularity is one hour.
- Spread batch jobs, such as creating many sub-users, over several minutes.
import os
import time
import requests
API = "https://api.proxonym.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PROXONYM_API_KEY']}"}
def api_get(path, params=None, attempts=5):
for _ in range(attempts):
r = requests.get(API + path, headers=HEADERS, params=params, timeout=30)
if r.status_code != 429:
r.raise_for_status()
return r.json()
time.sleep(int(r.headers.get("Retry-After", "5")))
raise RuntimeError(f"{path}: still rate limited after {attempts} attempts")
print(api_get("/usage", {"product": "residential", "granularity": "day"}))Errors#
Errors use standard HTTP status codes and a JSON body with a stable, machine-readable code and a human-readable message:
{
"error": {
"code": "invalid_api_key",
"message": "The API key is missing, malformed or revoked."
}
}Branch on code, never on message: messages can be reworded, codes stay stable.
| Status | Code | Meaning | What to do |
|---|---|---|---|
400 | invalid_request | The request is malformed: invalid JSON, a missing required parameter, or a value of the wrong type | Fix the request. Retrying won't help |
401 | invalid_api_key | The API key is missing, malformed or revoked | Check the header and the key |
403 | product_not_active, quota_exceeded | The key is valid, but the product has no active plan, or the SERP plan has no requests left | Buy or renew the plan |
404 | not_found | The path, product, sub-user ID or whitelisted IP doesn't exist | Check the path and the ID |
409 | already_exists | The IP is already whitelisted, or another sub-user has that name | Use the existing resource or choose another value |
422 | validation_failed, whitelist_full | A value is well formed but not accepted, such as an invalid IP, an unknown product or a date range that is too long, or every whitelist slot is taken | Correct the value, or remove an IP from the whitelist first |
429 | rate_limited | More than 60 requests in a minute | Wait Retry-After seconds, then retry |
500 | internal_error | An unexpected error on our side | Retry with exponential backoff |
Only 429 and 500 are worth retrying unchanged. If a 500 persists, note the endpoint, the time of the request and the full error body: on a dedicated datacenter plan, send them to our team in a ticket.
Account#
Read your account details, GB balances and active plans.
Get the account
GET /account
Returns the account, its GB balances and every active plan. Expired plans aren't included.
Parameters
None.
Example request
curl https://api.proxonym.com/v1/account \
-H "Authorization: Bearer $PROXONYM_API_KEY"Example response
{
"id": "acc_7d3f9k2m",
"email": "you@company.example",
"created_at": "2026-03-14T08:21:47Z",
"credit_usd": 245.5,
"balances": {
"residential": {
"gb_remaining": 37.836,
"expires_at": "2026-10-12T14:03:51Z",
"packs": [
{
"gb_purchased": 40,
"gb_remaining": 17.836,
"purchased_at": "2026-09-12T14:03:51Z",
"expires_at": "2026-10-12T14:03:51Z"
},
{
"gb_purchased": 20,
"gb_remaining": 20.0,
"purchased_at": "2026-08-02T16:40:55Z",
"expires_at": null
}
]
},
"datacenter": {
"gb_remaining": 687.52,
"expires_at": "2026-10-18T09:12:40Z"
}
},
"plans": [
{
"id": "pl_4k8d2pqm",
"product": "unlimited",
"bandwidth_mbps": 200,
"gateway": "use.unl.proxonym.com",
"udp": false,
"started_at": "2026-09-25T10:00:00Z",
"expires_at": "2026-10-02T10:00:00Z"
},
{
"id": "pl_3n7q1wza",
"product": "datacenter",
"ips": 1000,
"bandwidth_gb": 1000,
"started_at": "2026-09-18T09:12:40Z",
"expires_at": "2026-10-18T09:12:40Z"
},
{
"id": "pl_6t2r9exb",
"product": "isp",
"ips": 20,
"started_at": "2026-09-20T15:30:00Z",
"expires_at": "2026-10-20T15:30:00Z"
},
{
"id": "pl_2h5j8kvc",
"product": "serp",
"requests_limit": 100000,
"requests_used": 41827,
"started_at": "2026-09-08T11:45:19Z",
"expires_at": "2026-10-08T11:45:19Z"
}
]
}Response fields
| Field | Type | Description |
|---|---|---|
id | string | Account ID |
email | string | Account email address |
created_at | string | When the account was created |
credit_usd | number | Account balance in US dollars, available to buy plans. Top-ups and bonus credit add to it |
balances | object | GB balances keyed by product: residential, which mobile shares, and datacenter, the monthly bandwidth allowance. Products without a balance are left out |
balances.{product}.gb_remaining | number or null | GB left. null on the Unlimited datacenter tier |
balances.{product}.expires_at | string or null | Earliest expiry of the traffic in this balance. null if none of it expires |
balances.residential.packs[] | array | One entry per GB pack with traffic left: gb_purchased, gb_remaining, purchased_at and expires_at, which is null for packs with no expiry |
plans[] | array | Active plans. Every plan has id, product, status (active, or provisioning while static IPs are being prepared), started_at and expires_at |
plans[].bandwidth_mbps, gateway, udp | integer, string, boolean | Unlimited residential: speed tier, gateway server, and whether the UDP add-on is active |
plans[].ips | integer | ISP, datacenter and dedicated: number of IPs |
plans[].bandwidth_gb | integer or null | Datacenter: monthly bandwidth tier in GB, null on the Unlimited tier |
plans[].requests_limit, requests_used | integer | SERP API: requests included in the plan, and requests used so far |
Mobile traffic draws from the residential balance, so there is no mobile balance. Residential GB packs appear under balances, not plans. Plans never auto-renew: compare expires_at with the current time to decide when to renew.
Example: warn on a low balance
import os
import requests
r = requests.get(
"https://api.proxonym.com/v1/account",
headers={"Authorization": f"Bearer {os.environ['PROXONYM_API_KEY']}"},
timeout=30,
)
r.raise_for_status()
residential = r.json()["balances"].get("residential")
if residential is None or residential["gb_remaining"] < 5:
left = residential["gb_remaining"] if residential else 0
print(f"Residential balance is low: {left:.1f} GB left. Top up before jobs fail with 402.")Usage#
Read how much traffic, or how many SERP requests, you used over time.
Get usage
GET /usage
Returns the usage of one product over a time range, as a total and a time series.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
product | string, query | Yes | residential, mobile, unlimited, isp, datacenter, dedicated or serp |
from | string, query | No | Start of the range, inclusive: an ISO 8601 date or timestamp in UTC. Default: 7 days before to |
to | string, query | No | End of the range, exclusive. Default: now |
granularity | string, query | No | day (default) or hour. Buckets are aligned to UTC |
A range can span up to 366 days at day granularity and 31 days at hour. A longer range, or a from later than to, returns 422 with validation_failed. Mobile usage is reported on its own, but it's deducted from the residential balance.
Example request
curl -G https://api.proxonym.com/v1/usage \
-H "Authorization: Bearer $PROXONYM_API_KEY" \
-d product=residential \
-d from=2026-09-24 \
-d to=2026-10-01 \
-d granularity=dayExample response
{
"product": "residential",
"granularity": "day",
"from": "2026-09-24T00:00:00Z",
"to": "2026-10-01T00:00:00Z",
"total": {
"traffic_gb": 9.964
},
"series": [
{ "timestamp": "2026-09-24T00:00:00Z", "traffic_gb": 1.204 },
{ "timestamp": "2026-09-25T00:00:00Z", "traffic_gb": 1.587 },
{ "timestamp": "2026-09-26T00:00:00Z", "traffic_gb": 0.932 },
{ "timestamp": "2026-09-27T00:00:00Z", "traffic_gb": 1.411 },
{ "timestamp": "2026-09-28T00:00:00Z", "traffic_gb": 1.876 },
{ "timestamp": "2026-09-29T00:00:00Z", "traffic_gb": 1.309 },
{ "timestamp": "2026-09-30T00:00:00Z", "traffic_gb": 1.645 }
]
}Response fields
| Field | Type | Description |
|---|---|---|
product, granularity | string | The values used for the query |
from, to | string | The resolved range, as UTC timestamps |
total.traffic_gb | number | Traffic in the range, in GB. Proxy products only |
total.requests | integer | SERP API requests in the range. serp only |
series[] | array | One point per bucket, in time order. Buckets without usage report 0 |
series[].timestamp | string | Start of the bucket |
series[].traffic_gb or series[].requests | number or integer | Usage in the bucket, in the same unit as total |
For serp, totals and points count requests instead of GB. An hourly query such as ?product=serp&from=2026-09-30T00:00:00Z&to=2026-09-30T03:00:00Z&granularity=hour returns:
{
"product": "serp",
"granularity": "hour",
"from": "2026-09-30T00:00:00Z",
"to": "2026-09-30T03:00:00Z",
"total": {
"requests": 1854
},
"series": [
{ "timestamp": "2026-09-30T00:00:00Z", "requests": 612 },
{ "timestamp": "2026-09-30T01:00:00Z", "requests": 587 },
{ "timestamp": "2026-09-30T02:00:00Z", "requests": 655 }
]
}Proxy lists#
Download the proxies assigned to your static plans. Residential, mobile and unlimited residential have no list: they connect through a gateway, described in Endpoints and ports.
List proxies
GET /proxies/{product}
Returns every proxy of your active plans for one product, as JSON or as plain text with one proxy per line.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
product | string, path | Yes | datacenter, isp or dedicated |
format | string, query | No | json (default) or txt |
country | string, query | No | Return only proxies in this country: an ISO 3166-1 alpha-2 code in lowercase, such as us |
Example request
curl https://api.proxonym.com/v1/proxies/isp \
-H "Authorization: Bearer $PROXONYM_API_KEY"Example response
Trimmed to three entries; count is the full number.
{
"product": "isp",
"count": 20,
"proxies": [
{
"ip": "198.51.100.61",
"port": 6200,
"username": "isp_k8w2m4",
"password": "Tz6pW1qR8nVb3xYc",
"country": "us",
"location": "New York",
"expires_at": "2026-10-20T15:30:00Z"
},
{
"ip": "198.51.100.62",
"port": 6200,
"username": "isp_k8w2m4",
"password": "Tz6pW1qR8nVb3xYc",
"country": "us",
"location": "New York",
"expires_at": "2026-10-20T15:30:00Z"
},
{
"ip": "198.51.100.63",
"port": 6200,
"username": "isp_k8w2m4",
"password": "Tz6pW1qR8nVb3xYc",
"country": "us",
"location": "New York",
"expires_at": "2026-10-20T15:30:00Z"
}
]
}Plain text format
With format=txt, the response is text/plain with one proxy per line: ip:port for datacenter, where the port is the HTTP port, and ip:port:username:password for ISP and dedicated.
curl -G https://api.proxonym.com/v1/proxies/datacenter \
-H "Authorization: Bearer $PROXONYM_API_KEY" \
-d format=txt \
-d country=us198.51.100.23:3129
198.51.100.87:3129
198.51.100.142:3129Proxy fields
| Field | Products | Description |
|---|---|---|
ip | All | Proxy IP address |
port | ISP, dedicated | Port for both HTTP and SOCKS5 |
http_port, socks5_port | Datacenter | HTTP port 3129 and SOCKS5 port 1081 |
username, password | ISP, dedicated | Credentials for this proxy |
country | All | Country of the IP, as a lowercase ISO 3166-1 alpha-2 code |
location | ISP | City or carrier pool, such as New York or Comcast pool |
expires_at | ISP, dedicated | End of the term for this IP |
A datacenter entry in JSON looks like {"ip": "198.51.100.23", "http_port": 3129, "socks5_port": 1081, "country": "us"}. Without an active plan for the product, the API returns 403 with product_not_active. A product that has no list, such as residential, returns 404:
{
"error": {
"code": "not_found",
"message": "No proxy list for product residential. Lists exist for datacenter, isp and dedicated."
}
}Whitelist#
The whitelist lets machines connect to your shared datacenter proxies without credentials. Every shared datacenter plan includes 3 slots, and entries apply to all your datacenter IPs. Background: IP whitelist in the docs.
List whitelisted IPs
GET /whitelist
Parameters
None.
Example request
curl https://api.proxonym.com/v1/whitelist \
-H "Authorization: Bearer $PROXONYM_API_KEY"Example response
{
"limit": 3,
"ips": [
{ "ip": "192.0.2.10", "created_at": "2026-09-18T09:20:11Z" },
{ "ip": "192.0.2.57", "created_at": "2026-09-22T17:02:45Z" }
]
}limit is the number of slots on your account, and ips lists the entries, oldest first.
Add an IP
POST /whitelist
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
ip | string, body | Yes | Public IP address of the machine that will connect, such as 192.0.2.44 |
Example request
curl -X POST https://api.proxonym.com/v1/whitelist \
-H "Authorization: Bearer $PROXONYM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ip": "192.0.2.44"}'Example response
Status 201:
{
"ip": "192.0.2.44",
"created_at": "2026-10-01T09:30:00Z"
}An IP that is already listed returns 409 with already_exists, and an invalid address returns 422 with validation_failed. When every slot is taken, the API returns 422:
{
"error": {
"code": "whitelist_full",
"message": "All 3 whitelist slots are in use. Remove an IP before adding another."
}
}Remove an IP
DELETE /whitelist/{ip}
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
ip | string, path | Yes | The whitelisted IP to remove |
Example request
curl -X DELETE https://api.proxonym.com/v1/whitelist/192.0.2.10 \
-H "Authorization: Bearer $PROXONYM_API_KEY"Example response
{
"ip": "192.0.2.10",
"deleted": true
}From then on, requests from that IP without credentials fail with 407. An IP that isn't on the list returns 404 with not_found.
Sub-users#
Sub-users are extra proxy credentials under your account, each with an optional traffic limit. Their traffic counts against your account balance. Background: Sub-users in the docs.
The sub-user object
{
"id": "su_3k9x2m7q",
"name": "price-monitor",
"username": "sub_k3v9q2xd",
"password": "Qm7vT2xK9pLr4sWz",
"traffic_limit_gb": 25,
"traffic_used_gb": 6.412,
"status": "active",
"created_at": "2026-09-14T08:05:22Z"
}| Field | Type | Description |
|---|---|---|
id | string | Sub-user ID, used in API paths |
name | string | Your label for the sub-user, unique in your account |
username | string | Proxy username, generated. It takes the same options as your main username, such as sub_k3v9q2xd-country-us-session-a7k2 |
password | string | Proxy password, generated |
traffic_limit_gb | number or null | Maximum traffic in GB. null means no limit beyond your account balance |
traffic_used_gb | number | Traffic used so far, in GB |
status | string | active or disabled. The proxy answers 407 to disabled sub-users |
created_at | string | When the sub-user was created |
When traffic_used_gb reaches traffic_limit_gb, the sub-user's requests fail with 402 until you raise the limit.
List sub-users
GET /sub-users
Parameters
None.
Example request
curl https://api.proxonym.com/v1/sub-users \
-H "Authorization: Bearer $PROXONYM_API_KEY"Example response
{
"sub_users": [
{
"id": "su_3k9x2m7q",
"name": "price-monitor",
"username": "sub_k3v9q2xd",
"password": "Qm7vT2xK9pLr4sWz",
"traffic_limit_gb": 25,
"traffic_used_gb": 6.412,
"status": "active",
"created_at": "2026-09-14T08:05:22Z"
},
{
"id": "su_8d1f4n6p",
"name": "qa-team",
"username": "sub_p8w2n5tf",
"password": "Hx4bN9cR2vLq7mKs",
"traffic_limit_gb": null,
"traffic_used_gb": 1.207,
"status": "disabled",
"created_at": "2026-09-20T13:47:09Z"
}
]
}Create a sub-user
POST /sub-users
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
name | string, body | Yes | Label of 1 to 64 characters, unique in your account |
traffic_limit_gb | number or null, body | No | Traffic limit in GB, greater than 0. Omit it or send null for no limit |
Example request
curl -X POST https://api.proxonym.com/v1/sub-users \
-H "Authorization: Bearer $PROXONYM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "eu-crawler", "traffic_limit_gb": 10}'Example response
Status 201, with a generated username and password:
{
"id": "su_6v2c8r1t",
"name": "eu-crawler",
"username": "sub_t6r1y8bw",
"password": "Lp3sV8kQ1zXn6wRd",
"traffic_limit_gb": 10,
"traffic_used_gb": 0,
"status": "active",
"created_at": "2026-10-01T09:30:00Z"
}A name that's already taken returns 409 with already_exists. The new credentials work on the gateway right away, with the usual username options:
curl -x http://gw.proxonym.com:8000 \
-U "sub_t6r1y8bw-country-de:Lp3sV8kQ1zXn6wRd" \
https://api.ipify.orgUpdate a sub-user
PATCH /sub-users/{id}
Send only the fields you want to change.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string, path | Yes | Sub-user ID |
name | string, body | No | New label, 1 to 64 characters |
traffic_limit_gb | number or null, body | No | New limit in GB, or null for no limit |
status | string, body | No | active or disabled |
reset_password | boolean, body | No | true generates a new password. The old one stops working immediately |
Example request
Raise the limit and reset the password:
curl -X PATCH https://api.proxonym.com/v1/sub-users/su_3k9x2m7q \
-H "Authorization: Bearer $PROXONYM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"traffic_limit_gb": 40, "reset_password": true}'Example response
{
"id": "su_3k9x2m7q",
"name": "price-monitor",
"username": "sub_k3v9q2xd",
"password": "Wd5nX8qT3vKz6pRm",
"traffic_limit_gb": 40,
"traffic_used_gb": 6.412,
"status": "active",
"created_at": "2026-09-14T08:05:22Z"
}Delete a sub-user
DELETE /sub-users/{id}
Deletes the sub-user, and its credentials stop working immediately. Traffic it already used stays in your usage. To pause a sub-user instead, set its status to disabled.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string, path | Yes | Sub-user ID |
Example request
curl -X DELETE https://api.proxonym.com/v1/sub-users/su_8d1f4n6p \
-H "Authorization: Bearer $PROXONYM_API_KEY"Example response
{
"id": "su_8d1f4n6p",
"deleted": true
}An unknown ID returns 404 with not_found.
SERP API#
The Google SERP API returns Google search results as parsed JSON, for any country or city, on desktop or mobile. Each call returns one results page and counts as one request on your plan.
Search
GET https://serp.proxonym.com/v1/search
Send your SERP API key from the dashboard in the X-API-Key header. Errors use the same format as the account API: a missing or invalid key returns 401 with invalid_api_key. Without an active SERP plan, the API returns 403 with product_not_active, and once the plan's requests are used up, 403 with quota_exceeded.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
q | string | Yes | Search query, URL-encoded |
gl | string | No | Country of the results, as a lowercase ISO 3166-1 alpha-2 code. Default us |
hl | string | No | Interface language code, such as en or de. Default en |
location | string | No | City-level location written as City,Region, such as Chicago,Illinois. Use a place inside the gl country |
device | string | No | desktop (default) or mobile |
page | integer | No | Results page, starting at 1 (default). Each page is a separate request |
Example request
curl -G https://serp.proxonym.com/v1/search \
-H "X-API-Key: $PROXONYM_SERP_KEY" \
--data-urlencode "q=running shoes" \
-d gl=us \
-d hl=en \
--data-urlencode "location=Chicago,Illinois" \
-d device=desktop \
-d page=1The same request in Python:
import os
import requests
params = {
"q": "running shoes",
"gl": "us",
"hl": "en",
"location": "Chicago,Illinois",
"device": "desktop",
"page": 1,
}
r = requests.get(
"https://serp.proxonym.com/v1/search",
headers={"X-API-Key": os.environ["PROXONYM_SERP_KEY"]},
params=params,
timeout=60,
)
r.raise_for_status()
for result in r.json()["organic_results"]:
print(result["position"], result["title"], result["link"])Example response
Trimmed for length:
{
"search_parameters": {
"q": "running shoes",
"gl": "us",
"hl": "en",
"location": "Chicago,Illinois",
"device": "desktop",
"page": 1
},
"organic_results": [
{
"position": 1,
"title": "Running Shoes for Men and Women | Stride Supply",
"link": "https://www.stridesupply.example/running-shoes",
"snippet": "Shop road and trail running shoes in every size. Compare cushioning, drop and weight across 40 models."
},
{
"position": 2,
"title": "How to Choose Running Shoes: A Buyer's Guide",
"link": "https://www.runnersdesk.example/guides/choosing-running-shoes",
"snippet": "Gait, arch type and weekly mileage matter more than brand. Here is how to narrow the field."
},
{
"position": 3,
"title": "Running Shoes in Chicago, IL | Lakeshore Run Co.",
"link": "https://www.lakeshorerun.example/",
"snippet": "Gait analysis and fittings at our Lincoln Park store, open 7 days a week."
}
],
"ads": [
{
"position": 1,
"title": "Running Shoes Sale | Up to 40% Off",
"link": "https://www.shoeoutlet.example/running",
"snippet": "Last season's models in stock. Ships in 1 business day."
}
],
"people_also_ask": [
{
"question": "How often should you replace running shoes?",
"snippet": "Many runners replace their shoes every 300 to 500 miles.",
"link": "https://www.runnersdesk.example/guides/shoe-lifespan"
}
],
"related_searches": [
{ "query": "running shoes near me" },
{ "query": "trail running shoes" },
{ "query": "running shoes for flat feet" }
],
"local_results": [
{
"position": 1,
"title": "Lakeshore Run Co.",
"address": "2312 N Lincoln Ave, Chicago, IL",
"phone": "(312) 555-0142"
},
{
"position": 2,
"title": "Windy City Running",
"address": "845 W Randolph St, Chicago, IL",
"phone": "(312) 555-0187"
}
]
}Response fields
| Field | Type | Description |
|---|---|---|
search_parameters | object | The parameters of the search, with defaults filled in |
organic_results[] | array | Organic results in page order |
organic_results[].position | integer | Rank on the page, starting at 1 |
organic_results[].title | string | Result title |
organic_results[].link | string | Result URL |
organic_results[].snippet | string | Text shown under the title |
ads[] | array | Paid results, with position, title, link and snippet |
people_also_ask[] | array | Questions from the "People also ask" box, with question, snippet and link |
related_searches[] | array | Related queries, each with query |
local_results[] | array | Local pack results, with position, title, address and phone |
Blocks that don't appear on the page come back as empty arrays. To follow rankings over time, see the SERP tracking use case and our guide to scraping Google search results.