API

Country Targeting

You can target a specific country by adding a country code to your username, like username-country-country_code. Use only two-letter country codes in lowercase.

curl--proxy brd.superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>-country-us:<ZONE_PASSWORD

City Targeting

You can target a specific city within a country by adding a city name to the username, like username-country-country_code-city-city_code. The city_codemust be in lowercase only and have no spaces, for example -city-sanfrancisco

curl--proxy brd.superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>-country-us-city-sanfrancisco:<ZONE_PASSWORD> "http://target.site"

State Targeting

For relevant counties (e.g., USA and Australia), you can target a state within a country by adding to the username-country-country_code-state-state_code. Use only two-letter state codes in lowercase.

curl--proxy brd.superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>-country-us-state-ny:<ZONE_PASSWORD> "http://target.site"
curl--proxy brd.superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>-country-au-state-wa:<ZONE_PASSWORD> "http://target.site"

ASN targeting

You can target a specific ASN from the list of ASNs. Choosing an ASN country is done as following: -asn-ASN_NUMBER

curl--proxy brd.superproxy.ioio:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>-asn-56386:<ZONE_PASSWORD> "http://target.site"

ZIP code targeting

You can target proxy peers by a ZIP code of a specific area. Here is an example of targeting an IP from Memphis, US and zip code 12345:

curl--proxy brd.superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>-city-memphis-zip-12345:<ZONE_PASS

Control IP rotation 

By default, sending a request to the zone will return the fastest IP from the zone available now for your request.

If keeping the same IP for multiple requests is required, it could be done with the session ID request parameter.

The session ID is an element that allows control of IP rotation, as each unique session ID will get a unique IP. It's used by adding some string to the username -session-SESSION_ID, for example -session-mystring12345

curl--proxy brd.superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>-session-mystring12345:<ZONE_PASSWORD> "http://target.site"

Please note: our super-proxy will keep the session live for 60 seconds. If the interval between two requests is more than 60 seconds, the old session will be terminated, and a new session with the same name will be created, and another IP will be used for your requests.

Force API to keep the same proxy peer during your session

You can specify to our API that you need it to avoid assigning a new peer to the session in case the peer used in the session went offline. In case you are enforcing this request parameter, you will get a 502 error code for your request when that peer used for your session went offline, with error message:

502 Proxy Error: server_error Failed to establish connection with peer

This workflow can be useful for Residential and Mobile proxy zones, which consist of real PCs and mobile devices.

It's used by adding -const after your session name, for example -session-mystring12345-const

curl--proxy brd.superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>-session-mystring12345-const:<ZONE_PASSWORD> "http://target.site"

Selecting Super Proxy in a Specific Country

It is possible to require our load balancer to provide a super proxy in a specific country. 

Choosing the super proxy country can be done like this: servercountry-{country}.brd.superproxy.io. E.g. servercountry-gb.brd.superproxy.io

curl--proxy servercountry-gb.brd.superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> "htt

Controlling where DNS resolution is performed

When using local DNS resolution, domain names will be resolved and cached by the Super Proxy.

curl--proxy brd.superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>-dns-local:<ZONE_PASSWORD> "http://target.site"

When using remote, DNS resolution is made at the Proxy Peer. This is slower but will provide you with the same IP as a person browsing for a chosen country.

curl--proxy brd.superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>-dns-remote:<ZONE_PASSWORD> "http://target.site"

Request error handling

pass_dyn: if a request can't pass via proxy peer, automatically pass it via the Super Proxy

curl--proxy brd.superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>-route_err-pass_dyn:<ZONE_PASSWORD> "http://target.site"

block: if a request can't pass via proxy peer, block it and don't send via Super Proxy

curl--proxy brd.superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>-route_err-block:<ZONE_PASSWORD> "http://target.site"

Sending requests directly from Super Proxy 

You can choose to perform the request from the super proxy directly instead of the IP of the peer. In that case, the IP of the request will be the one of the Super Proxy by adding'-direct'to your request authorization string. 

curl--proxy brd.superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>-direct:<ZONE_PASSWORD> "http://target.site"

Carrier-specific proxy peer IP (Mobile Proxies)

  • You can choose to use a specific carrier from this list: a1, aircel, airtel, att, celcom, chinamobile, claro, comcast, cox, digi, dt, docomo, dtac, etisalat, idea, kyivstar, meo, megafon, mtn, mtnza, mts, optus, orange, qwest, reliance_jio, robi, sprint, telefonica, telstra, tmobile, tigo, tim, verizon, vimpelcom, vodacomza, vodafone, vivo, zain, vivabo, telenormyanmar, kcelljsc, swisscom, singtel, asiacell, windit, cellc, ooredoo, drei, umobile, cableone, proximus, tele2, mobitel, o2, bouygues, free, sfr, digicel
  • Example for carrier Deutsche Telekom: 

brd-customer-{YOUR_CUSTOMER_ID}-zone-{YOUR_ZONE}-carrier-dt

  • Example for carrier Sprint: 

brd-customer-{YOUR_CUSTOMER_ID}-zone-{YOUR_ZONE}-carrier-sprint

Target specific OS

Bright Data allows targeting the following Operating Systems:

  • Windows:
    curl --proxy brd.superproxy.io:22225 --proxy-user brd-customer-<USERNAME>-zone-<ZONE>-os-windows:<PASSWORD> "<TARGET SITE>"
  • MAC:
    curl --proxy brd.superproxy.io:22225 --proxy-user brd-customer-<USERNAME>-zone-<ZONE>-os-osx:<PASSWORD> "<TARGET SITE>"
  • Android:
    curl --proxy brd.superproxy.io:22225 --proxy-user brd-customer-<USERNAME>-zone-<ZONE>-os-android:<PASSWORD> "<TARGET SITE>

Selecting a Specific gIP

Option available only for Residential or Mobile zones with multiple IPs allocated. To target a specific gIP allocated to your zone, use -gip-gip_name request parameter.

curl--proxy brd.superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>-gip-us_7922_fl_hollywood_0:<ZONE_PASSWORD> "http://target.site"

Selecting a Specific IP

Option available only for zones with multiple IPs allocated. To target a specific IP allocated to your zone, use -ip-ip_address request parameter.

curl--proxy brd.superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>-ip-1.1.1.1.1:<ZONE_PASSWORD> "http://target.site"

 

API Token Options

Creating an API token

The following requests will require you to use Bright Data's API token as your authentication method. Please read about our API token and its usage.

In the next examples <ZONE> must be replaced with the Zone's name and <API_TOKEN> with the API TOKEN string value

Get all available Dedicated IPs per Zone

The API endpoint to gather a list of gIPs on a dedicated residential or mobile zone is:

GET /api/zone/route_vips

API endpoint: GET /api/zone/route_vips
Sample response: ["186XXXXXXXXXXX01","186XXXXXXXXXXX00"]
 
  • Shell

     curl -X GET "https://api.brightdata.com/zone/route_vips?zone=<ZONE>"  -H "Authorization: Bearer <API_TOKEN>"
  • Node.js - Request

    var request = require('request');
    var options = {
      'method': 'GET',
      'url': 'https://api.brightdata.com/zone/route_vips?zone=<ZONE>',
      'headers': {
        'Authorization': 'Bearer <API_TOKEN>'
      }
    };
    request(options, function (error, response) {
      if (error) throw new Error(error);
      console.log(response.body);
    });
    
  • Java

    package example;
    
    import org.apache.http.HttpHost;
    import org.apache.http.client.fluent.*;
    
    public class Example {
      public static void main(String[] args) throws Exception {
        String res = Executor.newInstance()
          .addHeader("Authorization", "Bearer <API_TOKEN>")      .execute(Request.Get("https://api.brightdata.com/zone/route_vips?zone=<ZONE>"))      .returnContent().asString();
        System.out.println(res)
      }}
  • C#

    using System;
    using System.Net;
    using System.Net.Http;
    using System.Net.Http.Headers;
    
    public class Program {
      public static async Task Main() {
        var client = new HttpClient();
        var requestMessage = new HttpRequestMessage {
          Method = HttpMethod.Get,      RequestUri = new Uri("https://api.brightdata.com/zone/route_vips?zone=ZONE"),
          Headers = {
            {"Authorization", "Bearer API_TOKEN"}
          }
        };
        var response = await client.SendAsync(requestMessage);
        var responseString = await response.Content.ReadAsStringAsync();
        Console.WriteLine(responseString);
      }
    }
    
  • Python - Requests

     import requests
    
    url = "https://api.brightdata.com/zone/route_vips?zone=<ZONE>"
    
    payload={}
    headers = {
      'Authorization': 'Bearer <API_TOKEN>'
    }
    
    response = requests.request("GET", url, headers=headers, data=payload)
    
    print(response.text)
    

Was this article helpful?