NewUnlimited residential proxies: unmetered traffic on a fixed price. From $33.25/day

API reference

Proxonym API reference

Manage balances, usage, proxy lists, the IP whitelist and sub-users over a JSON REST API, and fetch parsed Google results with the SERP API.

  • Base URLhttps://api.proxonym.com/v1
  • AuthAuthorization: Bearer API_KEY
  • FormatJSON
  • Rate limit60 / min

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

Text
https://api.proxonym.com/v1

Paths 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 with format=txt. Send request bodies as JSON with Content-Type: application/json.
  • Status codes: 200 on success and 201 when 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 as 2026-09-24, read as midnight UTC.
  • Traffic: gigabytes as decimal numbers, for example 17.836.
  • IDs: strings with a type prefix, such as su_3k9x2m7q for a sub-user. Treat them as opaque.
  • Missing values: null, for example "expires_at": null on a pack that never expires.
  • Products: residential, mobile, unlimited, isp, datacenter, dedicated and serp.

Endpoints

MethodPathDescription
GET/accountAccount, GB balances and active plans
GET/usageUsage of one product over time
GET/proxies/{product}Proxy list for datacenter, ISP or dedicated
GET/whitelistList whitelisted IPs
POST/whitelistAdd an IP to the whitelist
DELETE/whitelist/{ip}Remove an IP from the whitelist
GET/sub-usersList sub-users
POST/sub-usersCreate a sub-user
PATCH/sub-users/{id}Update a sub-user
DELETE/sub-users/{id}Delete a sub-user
GEThttps://serp.proxonym.com/v1/searchGoogle results as parsed JSON

Your first call

Create an API key in the dashboard, export it, then request your account:

Shell
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:

Text
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:

Shell
curl -i https://api.proxonym.com/v1/account \
  -H "Authorization: Bearer wrong_key"
Text
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

  1. Create a new key in the dashboard.
  2. Deploy it to every service that calls the API.
  3. 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:

HeaderDescription
X-RateLimit-LimitRequests allowed per minute: 60
X-RateLimit-RemainingRequests left in the current window
Retry-AfterOn 429 responses only: seconds to wait before the next request

Over the limit, the API answers 429:

Text
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.
Python
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:

JSON
{
  "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.

StatusCodeMeaningWhat to do
400invalid_requestThe request is malformed: invalid JSON, a missing required parameter, or a value of the wrong typeFix the request. Retrying won't help
401invalid_api_keyThe API key is missing, malformed or revokedCheck the header and the key
403product_not_active, quota_exceededThe key is valid, but the product has no active plan, or the SERP plan has no requests leftBuy or renew the plan
404not_foundThe path, product, sub-user ID or whitelisted IP doesn't existCheck the path and the ID
409already_existsThe IP is already whitelisted, or another sub-user has that nameUse the existing resource or choose another value
422validation_failed, whitelist_fullA 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 takenCorrect the value, or remove an IP from the whitelist first
429rate_limitedMore than 60 requests in a minuteWait Retry-After seconds, then retry
500internal_errorAn unexpected error on our sideRetry 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

Shell
curl https://api.proxonym.com/v1/account \
  -H "Authorization: Bearer $PROXONYM_API_KEY"

Example response

JSON
{
  "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

FieldTypeDescription
idstringAccount ID
emailstringAccount email address
created_atstringWhen the account was created
credit_usdnumberAccount balance in US dollars, available to buy plans. Top-ups and bonus credit add to it
balancesobjectGB balances keyed by product: residential, which mobile shares, and datacenter, the monthly bandwidth allowance. Products without a balance are left out
balances.{product}.gb_remainingnumber or nullGB left. null on the Unlimited datacenter tier
balances.{product}.expires_atstring or nullEarliest expiry of the traffic in this balance. null if none of it expires
balances.residential.packs[]arrayOne 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[]arrayActive 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, udpinteger, string, booleanUnlimited residential: speed tier, gateway server, and whether the UDP add-on is active
plans[].ipsintegerISP, datacenter and dedicated: number of IPs
plans[].bandwidth_gbinteger or nullDatacenter: monthly bandwidth tier in GB, null on the Unlimited tier
plans[].requests_limit, requests_usedintegerSERP 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

Python
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

NameTypeRequiredDescription
productstring, queryYesresidential, mobile, unlimited, isp, datacenter, dedicated or serp
fromstring, queryNoStart of the range, inclusive: an ISO 8601 date or timestamp in UTC. Default: 7 days before to
tostring, queryNoEnd of the range, exclusive. Default: now
granularitystring, queryNoday (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

Shell
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=day

Example response

JSON
{
  "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

FieldTypeDescription
product, granularitystringThe values used for the query
from, tostringThe resolved range, as UTC timestamps
total.traffic_gbnumberTraffic in the range, in GB. Proxy products only
total.requestsintegerSERP API requests in the range. serp only
series[]arrayOne point per bucket, in time order. Buckets without usage report 0
series[].timestampstringStart of the bucket
series[].traffic_gb or series[].requestsnumber or integerUsage 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:

JSON
{
  "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

NameTypeRequiredDescription
productstring, pathYesdatacenter, isp or dedicated
formatstring, queryNojson (default) or txt
countrystring, queryNoReturn only proxies in this country: an ISO 3166-1 alpha-2 code in lowercase, such as us

Example request

Shell
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.

JSON
{
  "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.

Shell
curl -G https://api.proxonym.com/v1/proxies/datacenter \
  -H "Authorization: Bearer $PROXONYM_API_KEY" \
  -d format=txt \
  -d country=us
Text
198.51.100.23:3129
198.51.100.87:3129
198.51.100.142:3129

Proxy fields

FieldProductsDescription
ipAllProxy IP address
portISP, dedicatedPort for both HTTP and SOCKS5
http_port, socks5_portDatacenterHTTP port 3129 and SOCKS5 port 1081
username, passwordISP, dedicatedCredentials for this proxy
countryAllCountry of the IP, as a lowercase ISO 3166-1 alpha-2 code
locationISPCity or carrier pool, such as New York or Comcast pool
expires_atISP, dedicatedEnd 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:

JSON
{
  "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

Shell
curl https://api.proxonym.com/v1/whitelist \
  -H "Authorization: Bearer $PROXONYM_API_KEY"

Example response

JSON
{
  "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

NameTypeRequiredDescription
ipstring, bodyYesPublic IP address of the machine that will connect, such as 192.0.2.44

Example request

Shell
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:

JSON
{
  "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:

JSON
{
  "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

NameTypeRequiredDescription
ipstring, pathYesThe whitelisted IP to remove

Example request

Shell
curl -X DELETE https://api.proxonym.com/v1/whitelist/192.0.2.10 \
  -H "Authorization: Bearer $PROXONYM_API_KEY"

Example response

JSON
{
  "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

JSON
{
  "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"
}
FieldTypeDescription
idstringSub-user ID, used in API paths
namestringYour label for the sub-user, unique in your account
usernamestringProxy username, generated. It takes the same options as your main username, such as sub_k3v9q2xd-country-us-session-a7k2
passwordstringProxy password, generated
traffic_limit_gbnumber or nullMaximum traffic in GB. null means no limit beyond your account balance
traffic_used_gbnumberTraffic used so far, in GB
statusstringactive or disabled. The proxy answers 407 to disabled sub-users
created_atstringWhen 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

Shell
curl https://api.proxonym.com/v1/sub-users \
  -H "Authorization: Bearer $PROXONYM_API_KEY"

Example response

JSON
{
  "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

NameTypeRequiredDescription
namestring, bodyYesLabel of 1 to 64 characters, unique in your account
traffic_limit_gbnumber or null, bodyNoTraffic limit in GB, greater than 0. Omit it or send null for no limit

Example request

Shell
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:

JSON
{
  "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:

Shell
curl -x http://gw.proxonym.com:8000 \
  -U "sub_t6r1y8bw-country-de:Lp3sV8kQ1zXn6wRd" \
  https://api.ipify.org

Update a sub-user

PATCH /sub-users/{id}

Send only the fields you want to change.

Parameters

NameTypeRequiredDescription
idstring, pathYesSub-user ID
namestring, bodyNoNew label, 1 to 64 characters
traffic_limit_gbnumber or null, bodyNoNew limit in GB, or null for no limit
statusstring, bodyNoactive or disabled
reset_passwordboolean, bodyNotrue generates a new password. The old one stops working immediately

Example request

Raise the limit and reset the password:

Shell
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

JSON
{
  "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

NameTypeRequiredDescription
idstring, pathYesSub-user ID

Example request

Shell
curl -X DELETE https://api.proxonym.com/v1/sub-users/su_8d1f4n6p \
  -H "Authorization: Bearer $PROXONYM_API_KEY"

Example response

JSON
{
  "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.

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

NameTypeRequiredDescription
qstringYesSearch query, URL-encoded
glstringNoCountry of the results, as a lowercase ISO 3166-1 alpha-2 code. Default us
hlstringNoInterface language code, such as en or de. Default en
locationstringNoCity-level location written as City,Region, such as Chicago,Illinois. Use a place inside the gl country
devicestringNodesktop (default) or mobile
pageintegerNoResults page, starting at 1 (default). Each page is a separate request

Example request

Shell
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=1

The same request in Python:

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:

JSON
{
  "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

FieldTypeDescription
search_parametersobjectThe parameters of the search, with defaults filled in
organic_results[]arrayOrganic results in page order
organic_results[].positionintegerRank on the page, starting at 1
organic_results[].titlestringResult title
organic_results[].linkstringResult URL
organic_results[].snippetstringText shown under the title
ads[]arrayPaid results, with position, title, link and snippet
people_also_ask[]arrayQuestions from the "People also ask" box, with question, snippet and link
related_searches[]arrayRelated queries, each with query
local_results[]arrayLocal 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.