Nstbrowser SDK for Python
A Python SDK for interacting with Nstbrowser API v2
Overview
This SDK implements Nstbrowser API v2, which is the recommended API with complete functionality from v1 plus additional features. It provides a comprehensive set of tools for managing browser profiles, controlling browser instances, managing local browser data, and utilizing Chrome DevTools Protocol (CDP) for browser automation.
The SDK enables you to:
- Create and manage browser profiles with detailed fingerprint configurations
- Start and stop browser instances individually or in batch
- Configure and manage proxies for profiles
- Manage profile tags for better organization
- Clear browser cache and cookies
- Connect to browsers using Chrome DevTools Protocol (CDP)
- Automate browser actions through CDP integration
Installation
pip install nstbrowser
pip install nstbrowser
Getting Started
To use the SDK, you need an API key from Nstbrowser:
from nstbrowser import NstbrowserClient
# Initialize the client with your API key
client = NstbrowserClient(api_key="your_api_key")
# Now you can use the various services
profile_id = "your_profile_id"
# Start a browser instance
response = client.browsers.start_browser(profile_id=profile_id)
print(f"Browser started: {response}")
# Stop the browser instance
response = client.browsers.stop_browser(profile_id=profile_id)
print(f"Browser stopped: {response}")
from nstbrowser import NstbrowserClient
# Initialize the client with your API key
client = NstbrowserClient(api_key="your_api_key")
# Now you can use the various services
profile_id = "your_profile_id"
# Start a browser instance
response = client.browsers.start_browser(profile_id=profile_id)
print(f"Browser started: {response}")
# Stop the browser instance
response = client.browsers.stop_browser(profile_id=profile_id)
print(f"Browser stopped: {response}")
Available Services
The SDK provides the following services:
BrowsersService
Manages browser instances, including starting, stopping, and getting information about browsers.
# Start a browser for a specific profile
response = client.browsers.start_browser(profile_id="your_profile_id")
# Start multiple browsers in batch
response = client.browsers.start_browsers(profile_ids=["profile_id_1", "profile_id_2"])
# Start a once-off browser with custom configuration
config = {
"name": "testProfile",
"platform": "Windows",
"kernelMilestone": "132",
"headless": False,
"proxy": "http://admin:[email protected]:8000",
"fingerprint": {
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...",
"screen": {"width": 1280, "height": 1024}
},
"startupUrls": ["https://www.example.com"]
}
response = client.browsers.start_once_browser(data=config)
# Stop a browser
response = client.browsers.stop_browser(profile_id="your_profile_id")
# Stop multiple browsers
response = client.browsers.stop_browsers(profile_ids=["profile_id_1", "profile_id_2"])
# Get active browsers
response = client.browsers.get_browsers(status="running")
# Get browser pages
response = client.browsers.get_browser_pages(profile_id="your_profile_id")
# Get browser debugger information
response = client.browsers.get_browser_debugger(profile_id="your_profile_id")
# Start a browser for a specific profile
response = client.browsers.start_browser(profile_id="your_profile_id")
# Start multiple browsers in batch
response = client.browsers.start_browsers(profile_ids=["profile_id_1", "profile_id_2"])
# Start a once-off browser with custom configuration
config = {
"name": "testProfile",
"platform": "Windows",
"kernelMilestone": "132",
"headless": False,
"proxy": "http://admin:[email protected]:8000",
"fingerprint": {
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...",
"screen": {"width": 1280, "height": 1024}
},
"startupUrls": ["https://www.example.com"]
}
response = client.browsers.start_once_browser(data=config)
# Stop a browser
response = client.browsers.stop_browser(profile_id="your_profile_id")
# Stop multiple browsers
response = client.browsers.stop_browsers(profile_ids=["profile_id_1", "profile_id_2"])
# Get active browsers
response = client.browsers.get_browsers(status="running")
# Get browser pages
response = client.browsers.get_browser_pages(profile_id="your_profile_id")
# Get browser debugger information
response = client.browsers.get_browser_debugger(profile_id="your_profile_id")
ProfilesService
Manages browser profiles, including creation, deletion, proxy configuration, and tag management.
# Create a new profile
profile_data = {
"name": "New Profile",
"platform": "Windows",
"kernelMilestone": "132",
"fingerprint": {
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...",
"timezone": "Asia/Hong_Kong"
}
}
response = client.profiles.create_profile(data=profile_data)
# Get profiles with filtering
response = client.profiles.get_profiles(data={"page": 1, "pageSize": 10})
# Delete a profile
response = client.profiles.delete_profile(profile_id="your_profile_id")
# Delete multiple profiles
response = client.profiles.delete_profiles(profile_ids=["profile_id_1", "profile_id_2"])
# Update a profile's proxy
response = client.profiles.update_profile_proxy(profile_id="your_profile_id", data={"url": "http://admin:[email protected]:8000"})
# Reset a profile's proxy
response = client.profiles.reset_profile_proxy(profile_id="your_profile_id")
# Manage profile tags
response = client.profiles.create_profile_tags(profile_id="your_profile_id", data=[{"name": "social", "color": "#646AEE"}])
response = client.profiles.get_profile_tags()
# Create a new profile
profile_data = {
"name": "New Profile",
"platform": "Windows",
"kernelMilestone": "132",
"fingerprint": {
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...",
"timezone": "Asia/Hong_Kong"
}
}
response = client.profiles.create_profile(data=profile_data)
# Get profiles with filtering
response = client.profiles.get_profiles(data={"page": 1, "pageSize": 10})
# Delete a profile
response = client.profiles.delete_profile(profile_id="your_profile_id")
# Delete multiple profiles
response = client.profiles.delete_profiles(profile_ids=["profile_id_1", "profile_id_2"])
# Update a profile's proxy
response = client.profiles.update_profile_proxy(profile_id="your_profile_id", data={"url": "http://admin:[email protected]:8000"})
# Reset a profile's proxy
response = client.profiles.reset_profile_proxy(profile_id="your_profile_id")
# Manage profile tags
response = client.profiles.create_profile_tags(profile_id="your_profile_id", data=[{"name": "social", "color": "#646AEE"}])
response = client.profiles.get_profile_tags()
LocalsService
Manages local browser data, such as cache and cookies.
# Clear browser cache
response = client.locals.clear_profile_cache(profile_id="your_profile_id")
# Clear browser cookies
response = client.locals.clear_profile_cookies(profile_id="your_profile_id")
# Clear browser cache
response = client.locals.clear_profile_cache(profile_id="your_profile_id")
# Clear browser cookies
response = client.locals.clear_profile_cookies(profile_id="your_profile_id")
CdpEndpointsService
Provides connections to browsers using Chrome DevTools Protocol (CDP) for automation.
# Connect to a browser using CDP
config = {
"headless": False,
"autoClose": False
}
response = client.cdp_endpoints.connect_browser(profile_id="your_profile_id", config=config)
# Connect to a once-off browser using CDP
config = {
"name": "testProfile",
"platform": "Windows",
"kernelMilestone": "132",
"autoClose": False,
"headless": False
}
response = client.cdp_endpoints.connect_once_browser(config=config)
# Connect to a browser using CDP
config = {
"headless": False,
"autoClose": False
}
response = client.cdp_endpoints.connect_browser(profile_id="your_profile_id", config=config)
# Connect to a once-off browser using CDP
config = {
"name": "testProfile",
"platform": "Windows",
"kernelMilestone": "132",
"autoClose": False,
"headless": False
}
response = client.cdp_endpoints.connect_once_browser(config=config)
Examples
The SDK comes with a comprehensive set of examples in the /examples
directory, organized by service:
Browser Examples
browsers/start_browser.py
: Start a browser for a specific profilebrowsers/start_browsers.py
: Start multiple browsers in batchbrowsers/start_once_browser.py
: Start a once-off browser with custom configurationbrowsers/stop_browser.py
: Stop a browserbrowsers/stop_browsers.py
: Stop multiple browsersbrowsers/get_browsers.py
: Get browser status informationbrowsers/get_browser_pages.py
: Get browser pages informationbrowsers/get_browser_debugger.py
: Get browser debugger information
Profile Examples
profiles/create_profile.py
: Create a new profile with detailed configurationprofiles/get_profiles.py
: Get profiles with filtering optionsprofiles/delete_profile.py
: Delete a specific profileprofiles/delete_profiles.py
: Delete multiple profilesprofiles/update_profile_proxy.py
: Update a profile's proxyprofiles/batch_update_proxy.py
: Update proxies for multiple profilesprofiles/reset_profile_proxy.py
: Reset a profile's proxyprofiles/batch_reset_profile_proxy.py
: Reset proxies for multiple profilesprofiles/create_profile_tags.py
: Create tags for a profileprofiles/get_profile_tags.py
: Get all profile tagsprofiles/update_profile_tags.py
: Update tags for a profileprofiles/batch_update_profile_tags.py
: Update tags for multiple profilesprofiles/clear_profile_tags.py
: Clear all tags from a profileprofiles/batch_clear_profile_tags.py
: Clear tags from multiple profilesprofiles/batch_create_profile_tags.py
: Create tags for multiple profilesprofiles/get_all_profile_groups.py
: Get all profile groupsprofiles/change_profile_group.py
: Change a profile groupprofiles/batch_change_profile_group.py
: Batch changes to profile groups
Local Data Examples
locals/clear_profile_cache.py
: Clear browser cachelocals/clear_profile_cookies.py
: Clear browser cookies
CDP Endpoint Examples
cdp_endpoints/connect_browser.py
: Connect to a browser using CDP and automate with Playwrightcdp_endpoints/connect_once_browser.py
: Connect to a once-off browser with CDP and automate with Playwright
To run an example:
python examples/browsers/start_browser.py
python examples/browsers/start_browser.py
CDP Integration with Playwright
One powerful feature is the ability to connect to browsers using Chrome DevTools Protocol (CDP) and automate them with Playwright:
# Get the CDP WebSocket URL
websocket_url = client.cdp_endpoints.connect_browser(
profile_id="your_profile_id",
config={"headless": False}
)["data"]["webSocketDebuggerUrl"]
# Use the URL with Playwright for automation
from playwright.async_api import async_playwright
async def automate():
async with async_playwright() as p:
browser = await p.chromium.connect_over_cdp(websocket_url)
page = browser.contexts[0].pages[0]
await page.goto("https://example.com")
# ... perform other actions
# Get the CDP WebSocket URL
websocket_url = client.cdp_endpoints.connect_browser(
profile_id="your_profile_id",
config={"headless": False}
)["data"]["webSocketDebuggerUrl"]
# Use the URL with Playwright for automation
from playwright.async_api import async_playwright
async def automate():
async with async_playwright() as p:
browser = await p.chromium.connect_over_cdp(websocket_url)
page = browser.contexts[0].pages[0]
await page.goto("https://example.com")
# ... perform other actions
Complete examples for CDP automation are available in the examples/cdp_endpoints
directory.
Support
For support, feel free to reach out to us via Discord. For more detailed documentation, visit the official Nstbrowser documentation: Nstbrowser API Documentation.