NativePort
Sign in Get a key
← How-to

How to Use Serper Google Search Through NativePort in Python

Pull real Google search results as structured JSON in one request — the fastest, cheapest way to ground an agent in the live web — through NativePort's Serper proxy, in plain Python.

Serper answers a query against Google itself and hands the result back as JSON in about a second, at a fraction of what other SERP APIs charge — which is why LangChain, CrewAI and most agent frameworks that ship a default web search tool ship this one. NativePort proxies Serper’s whole documented endpoint set under one key; this guide covers /search, the one call behind most of what gets built on top of it.

What you’ll need

  • A NativePort API key. Sign up to get a key and $5 in credits.
  • Python 3, standard library only — the example below uses urllib.request, no pip install.
  • Your key exported as an environment variable, never hardcoded:
export NATIVEPORT_API_KEY="np_..."

import json
import os
import urllib.request

GATEWAY = "https://api.nativeport.ai"
API_KEY = os.environ["NATIVEPORT_API_KEY"]


def search(q, **params):
    body = json.dumps({"q": q, **params}).encode()
    req = urllib.request.Request(f"{GATEWAY}/serper/search", data=body, method="POST")
    req.add_header("Authorization", f"Bearer {API_KEY}")
    req.add_header("Content-Type", "application/json")
    req.add_header("User-Agent", "nativeport-python-guide/1.0")
    with urllib.request.urlopen(req, timeout=30) as resp:
        return json.loads(resp.read())


result = search("site:github.com nativeport", num=10)
for item in result["organic"]:
    print(item["position"], item["title"], item["link"])

q is the only required field. gl (country code), hl (language), num (result count), page and autocorrect are Serper’s own optional controls and forward through unchanged. The response is Serper’s own JSON, exactly as their API returns it — organic is the array most callers want, each entry carrying at minimum title, link, snippet and position:

{
  "searchParameters": {"q": "site:github.com nativeport", "num": 10},
  "organic": [
    {"title": "nativeport-ai", "link": "https://github.com/...", "snippet": "...", "position": 1}
  ],
  "credits": 1
}

Depending on the query, the response can also carry a knowledgeGraph, an answerBox, peopleAlsoAsk and relatedSearches — Serper’s own vertical-specific fields, documented on their side rather than the gateway’s, so treat anything past organic as a bonus rather than something to depend on for every query.

The other verticals

/search is an alias for the bare /serper path, and it’s one of thirteen endpoints the gateway admits — swap the path segment and the request shape carries over: images, videos, places, maps, reviews, news, shopping, lens, scholar, patents and autocomplete all take the same {"q": ...} body against google.serper.dev, each returning its own result array (images, news, places, and so on) in place of organic.

webpage is the odd one out: it routes to a different Serper host (scrape.serper.dev, not google.serper.dev) and takes a URL rather than a query — {"url": "https://example.com", "includeMarkdown": true} — returning the page’s extracted text and, if requested, markdown. Same key, same Authorization header, different body shape.

Serper’s /account endpoint (the shared account’s remaining credit balance) is deliberately not exposed — it’s billing metadata for the whole account, not a search result, and no per-client key has a legitimate reason to read it. Any subpath outside the thirteen listed above (search, the eleven other verticals, and webpage) 404s before it reaches Serper.

Errors you’ll actually hit

  • 402 Payment Required: the NativePort balance is at $0. Every request answers this deterministically rather than degrading, so top up and retry.
  • 401 Unauthorized: the Authorization: Bearer <NATIVEPORT_API_KEY> header is missing, malformed, or doesn’t resolve to an account.
  • 403 Forbidden: the key is valid but the account isn’t active.
  • 404 on /serper/account or any endpoint not in Serper’s admitted list: not rate-limited or degraded, just not reachable — see above.
  • A 200 with an empty organic array: Serper itself found nothing for that query, not a gateway fault. Worth checking the query against Google directly before assuming something’s broken.

Security

Treat NATIVEPORT_API_KEY like any other credential: environment variable or secret store, never a literal string in source, never logged. Serper’s own X-API-KEY never reaches your process — the gateway injects it server-side.

What this costs

Serper reports the credits an individual call actually charged in a top-level credits field of its own response — most verticals bill 1, the webpage scraper bills 2 — and that’s what gets metered, at Serper’s own per-credit rate with no NativePort markup. Current pricing is on the Serper provider page. A zero balance answers every request with 402 instead of degrading. Adding credit carries a flat 5.5% fee on top-ups between $10 and $5,000 — never on the calls themselves. Full breakdown: pricing.

Where to go next