{ "openapi": "3.1.0", "info": { "title": "Bright Data Unblocker and SERP API (Async)", "description": "API for asynchronous web data collection using Unblocker and SERP engines.", "version": "1.0.0" }, "servers": [ { "url": "https://api.brightdata.com" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/unblocker/req": { "post": { "parameters": [ { "in": "query", "name": "zone", "description": "The name of your Bright Data Unlocker zone.", "required": true, "schema": { "type": "string" }, "example": "web_unlocker1" }, { "in": "query", "name": "customer", "description": "Your Bright Data account ID.", "schema": { "type": "string" }, "example": "hl_xxxxxxxx" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "description": "Defines the url of the request", "type": "string", "format": "uri", "example": "https://geo.brdtest.com/welcome.txt" }, "method": { "description": "Defines the HTTP method of the request", "type": "string" }, "headers": { "description": "Defines headers to be used in the request", "type": "object" }, "body": { "description": "Defines body to be sent with request. If an object is specified, it is serialized to JSON, and Content-Type header is set to application/json.", "oneOf": [ { "type": "string", "description": "Raw request body as a string." }, { "type": "object", "description": "Request body as a JSON object." } ] }, "country": { "description": "Defines country to be used for request (2-letters code)", "type": "string", "example": "US" }, "webhook_url": { "description": "Defines the URL to which the job status notification will be sent. If you don’t want to setup a default webhook or prefer the URL to be different per request, use this.", "type": "string", "format": "uri" }, "webhook_method": { "description": "Defines the HTTP method to use with the webhook_url (GET or POST)", "type": "string" }, "webhook_data": { "description": "Defines the data that will be sent with job status notification" }, "debug": { "description": "Set to `true` to return the `x-brd-debug` header. The header is returned by `GET /unblocker/get_result` when you collect the response, not on this submit call. See [Debugging Web Unlocker API](https://docs.brightdata.com/scraping-automation/web-unlocker/features#debugging-web-unlocker-api).", "type": "boolean", "default": false, "example": true } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } } }, "x-codeSamples": [ { "lang": "shell", "label": "cURL", "source": "curl --request POST \\\n --url \"https://api.brightdata.com/unblocker/req?zone=web_unlocker1\" \\\n --header \"Authorization: Bearer YOUR_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"url\": \"https://geo.brdtest.com/welcome.txt\"\n }'\n\n# => {\"response_id\":\"s4t7w3619285042ra9dke1m8qx\"}\n# Keep the response_id: you need it to collect the result." }, { "lang": "python", "label": "Python", "source": "import requests\n\nurl = \"https://api.brightdata.com/unblocker/req\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_API_KEY\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"url\": \"https://geo.brdtest.com/welcome.txt\",\n}\n\nresponse = requests.post(url, params={\"zone\": \"web_unlocker1\"},\n headers=headers, json=payload)\nresponse.raise_for_status()\n\n# Keep the response_id: you need it to collect the result.\nresponse_id = response.json()[\"response_id\"]\nprint(response_id)" }, { "lang": "javascript", "label": "JavaScript", "source": "const response = await fetch(\n \"https://api.brightdata.com/unblocker/req?zone=web_unlocker1\",\n {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer YOUR_API_KEY\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n url: \"https://geo.brdtest.com/welcome.txt\",\n }),\n },\n);\n\n// Keep the response_id: you need it to collect the result.\nconst { response_id } = await response.json();\nconsole.log(response_id);" }, { "lang": "go", "label": "Go", "source": "package main\n\nimport (\n\t\"bytes\"\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"net/http\"\n)\n\nfunc main() {\n\tpayload := []byte(`{\"url\":\"https://geo.brdtest.com/welcome.txt\"}`)\n\n\treq, _ := http.NewRequest(\"POST\",\n\t\t\"https://api.brightdata.com/unblocker/req?zone=web_unlocker1\",\n\t\tbytes.NewBuffer(payload))\n\treq.Header.Set(\"Authorization\", \"Bearer YOUR_API_KEY\")\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\n\t// Keep the ResponseID: you need it to collect the result.\n\tvar job struct {\n\t\tResponseID string `json:\"response_id\"`\n\t}\n\tjson.NewDecoder(res.Body).Decode(&job)\n\tfmt.Println(job.ResponseID)\n}" } ] } }, "/serp/req": { "post": { "parameters": [ { "in": "query", "name": "zone", "description": "The name of your Bright Data Unlocker zone.", "required": true, "schema": { "type": "string" }, "example": "web_unlocker1" }, { "in": "query", "name": "customer", "description": "Your Bright Data account ID.", "schema": { "type": "string" }, "example": "hl_xxxxxxxx" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "country": { "description": "Defines country to be used for request (2-letters code)", "type": "string", "example": "US" }, "query": { "description": "", "type": "object", "required": [ "q" ], "properties": { "q": { "description": "The search query parameter. Specifies the keyword or phrase you want to search for on Google.", "type": "string", "example": "pizza" }, "gl": { "description": "Two-letter country code used to define the country of search", "type": "string", "example": "au" }, "hl": { "description": "Two-letter language code used to define the page languages", "type": "string", "example": "en" }, "start": { "description": "Define the result offset - results to start from the selected value. Used for managing pagination.", "type": "integer", "example": 20 } } }, "brd_json": { "description": "Defines the response format", "type": "string", "enum": [ "json", "html" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } } } } }, "/unblocker/get_result": { "get": { "parameters": [ { "in": "query", "name": "response_id", "description": "Defines the job id. Received in the response headers of your initial [async request](https://docs.brightdata.com/api-reference/rest-api/unlocker/request).", "required": true, "schema": { "type": "string" }, "example": "s4t7w3619285042ra9dke1m8qx" }, { "in": "query", "name": "zone", "description": "The name of your Bright Data Unlocker zone.", "schema": { "type": "string" }, "example": "web_unlocker1" }, { "in": "query", "name": "customer", "description": "Your Bright Data account ID.", "schema": { "type": "string" }, "example": "hl_xxxxxxxx" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "status_code": 200, "headers": { "access-control-allow-origin": "*", "cache-control": "no-store", "content-type": "text/plain; charset=utf-8", "date": "Sun, 18 May 2025 20:01:18 GMT", "server": "nginx", "connection": "close", "transfer-encoding": "chunked" }, "body": "\nWelcome to Bright Data! Here are your proxy details\nCountry: US\nLatitude: 37.751\nLongitude: -97.822\nTimezone: America/Chicago\nASN number: 20473\nASN Organization name: AS-VULTR\nIP version: IPv4\n\nCommon usage examples:\n\n[USERNAME]-country-us:[PASSWORD] // US based Proxy\n[USERNAME]-country-us-state-ny:[PASSWORD] // US proxy from NY\n[USERNAME]-asn-56386:[PASSWORD] // proxy from ASN 56386\n[USERNAME]-ip-1.1.1.1.1:[PASSWORD] // proxy from dedicated pool\n\nTo get a simple JSON response, use https://geo.brdtest.com/mygeo.json .\n\nMore examples on https://docs.brightdata.com/api-reference/introduction\n\n" } } } }, "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestPending" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } } }, "x-codeSamples": [ { "lang": "shell", "label": "cURL", "source": "# Wait ~20s before the first poll, 10s before the second, then 5s.\n# HTTP 202 means the job is still running; 200 returns the result.\ncurl --request GET \\\n --url \"https://api.brightdata.com/unblocker/get_result?response_id=YOUR_RESPONSE_ID\" \\\n --header \"Authorization: Bearer YOUR_API_KEY\"" }, { "lang": "python", "label": "Python", "source": "import time\nimport requests\n\nurl = \"https://api.brightdata.com/unblocker/get_result\"\nheaders = {\"Authorization\": \"Bearer YOUR_API_KEY\"}\nparams = {\"response_id\": \"YOUR_RESPONSE_ID\"}\n\n# Wait ~20s before the first poll, 10s before the second, then 5s.\nfor delay in [20, 10] + [5] * 20:\n time.sleep(delay)\n response = requests.get(url, params=params, headers=headers)\n if response.status_code == 202:\n continue # still processing\n response.raise_for_status()\n print(response.json())\n break\nelse:\n raise TimeoutError(\"Result was not ready in time\")" }, { "lang": "javascript", "label": "JavaScript", "source": "const sleep = (ms) => new Promise((r) => setTimeout(r, ms));\n\n// Wait ~20s before the first poll, 10s before the second, then 5s.\nconst delays = [20_000, 10_000, ...Array(20).fill(5_000)];\n\nfor (const delay of delays) {\n await sleep(delay);\n\n const response = await fetch(\n \"https://api.brightdata.com/unblocker/get_result?response_id=YOUR_RESPONSE_ID\",\n { headers: { \"Authorization\": \"Bearer YOUR_API_KEY\" } },\n );\n\n if (response.status === 202) continue; // still processing\n\n console.log(await response.json());\n break;\n}" }, { "lang": "go", "label": "Go", "source": "package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"time\"\n)\n\nfunc main() {\n\turl := \"https://api.brightdata.com/unblocker/get_result?response_id=YOUR_RESPONSE_ID\"\n\n\t// Wait ~20s before the first poll, 10s before the second, then 5s.\n\tdelays := append([]time.Duration{20 * time.Second, 10 * time.Second},\n\t\tmake([]time.Duration, 20)...)\n\tfor i := 2; i < len(delays); i++ {\n\t\tdelays[i] = 5 * time.Second\n\t}\n\n\tfor _, d := range delays {\n\t\ttime.Sleep(d)\n\n\t\treq, _ := http.NewRequest(\"GET\", url, nil)\n\t\treq.Header.Set(\"Authorization\", \"Bearer YOUR_API_KEY\")\n\n\t\tres, err := http.DefaultClient.Do(req)\n\t\tif err != nil {\n\t\t\tpanic(err)\n\t\t}\n\n\t\tif res.StatusCode == http.StatusAccepted { // still processing\n\t\t\tres.Body.Close()\n\t\t\tcontinue\n\t\t}\n\n\t\tbody, _ := io.ReadAll(res.Body)\n\t\tres.Body.Close()\n\t\tfmt.Println(string(body))\n\t\treturn\n\t}\n\n\tpanic(\"result was not ready in time\")\n}" } ] } }, "/serp/get_result": { "get": { "parameters": [ { "in": "query", "name": "response_id", "description": "Defines the job id. Received in the response headers of your initial [async request](https://docs.brightdata.com/api-reference/rest-api/serp/request)", "required": true, "schema": { "type": "string" }, "example": "s4t7w3619285042ra9dke1m8qx" }, { "in": "query", "name": "zone", "description": "The name of your Bright Data Unlocker zone.", "schema": { "type": "string" }, "example": "web_unlocker1" }, { "in": "query", "name": "customer", "description": "Your Bright Data account ID.", "schema": { "type": "string" }, "example": "hl_xxxxxxxx" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "general": { "search_engine": "google", "query": "pizza", "results_cnt": 1200000000, "search_time": 0.45, "language": "en", "location": "United States", "mobile": false, "basic_view": false, "search_type": "text", "page_title": "pizza - Google Search", "timestamp": "2026-02-19T09:23:10.353Z" }, "input": { "original_url": "http://www.google.com/search?q=pizza&hl=en&gl=us" }, "organic": [ { "link": "https://www.pizzahut.com/", "source": "Pizza Hut", "display_link": "https://www.pizzahut.com", "title": "Pizza Hut | Delivery & Carryout - No One OutPizzas The Hut!", "description": "Discover classic & new menu items, find deals and enjoy seamless ordering for delivery and carryout. No One OutPizzas the Hut®.", "snippet_highlighted_words": [ "classic & new menu items" ], "icon": "data:image/png;base64 ...", "image": "data:image/jpeg;base64 ...", "image_alt": "pizza from www.pizzahut.com", "image_base64": "data:image/jpeg;base64 ...", "rank": 1, "global_rank": 4 }, { "link": "https://www.dominos.com/", "source": "Domino's", "display_link": "https://www.dominos.com", "title": "Domino's: Pizza Delivery & Carryout, Pasta, Wings & More", "description": "Order pizza, pasta, sandwiches & more online for carryout or delivery from Domino's. View menu, find locations, track orders. Sign up for Domino's email ...", "snippet_highlighted_words": [ "Order pizza, pasta, sandwiches & more online for carryout or delivery" ], "icon": "data:image/png;base64, ...", "rank": 2, "global_rank": 5 }, { "link": "https://en.wikipedia.org/wiki/Pizza", "source": "Wikipedia", "display_link": "https://en.wikipedia.org › wiki › Pizza", "title": "Pizza", "description": "Pizza is an Italian dish typically consisting of a flat base of leavened wheat-based dough topped with tomato, cheese, and other ingredients, baked at a ...Read more", "snippet_highlighted_words": [ "an Italian dish typically consisting of a flat base of leavened wheat-based dough" ], "icon": "data:image/png;base64 ...", "image": "data:image/jpeg;base64 ...", "image_alt": "pizza from en.wikipedia.org", "image_base64": "data:image/jpeg;base64 ...", "rank": 3, "global_rank": 6 } ], "perspectives": [ { "title": "Barstool Pizza Review - Flour + Water Pizzeria (San Francisco, CA)", "author": "One Bite Pizza Reviews · YouTube", "source": "Pizza reviews & rankings", "date": "97.3K+ views · 10 hours ago", "link": "https://www.youtube.com/watch?v=7iWWdSsTI0I", "image": "https://img.youtube.com/vi/7iWWdSsTI0I/hqdefault.jpg", "image_url": "https://img.youtube.com/vi/7iWWdSsTI0I/hqdefault.jpg" }, { "title": "Are there any just Sicilian style pizza places?", "author": "Pizzaholics · Facebook", "source": "Pizza enthusiast", "date": "8 reactions · 9 hours ago", "link": "https://www.facebook.com/groups/742034912983989/posts/2424981814689282/", "image": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcTAPzkwKJX8rct5LhEtAN6p-ypb5UjDiHn0aZ8e9S6nS8tPmROY_1E2gFxXeus&usqp=CAI&s", "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcTAPzkwKJX8rct5LhEtAN6p-ypb5UjDiHn0aZ8e9S6nS8tPmROY_1E2gFxXeus&usqp=CAI&s" }, { "title": "Top Pizza in the Bay Area", "author": "Cesar Hernandez, Soleil Ho", "source": "San Francisco Chronicle", "date": "2 weeks ago", "link": "https://www.sfchronicle.com/projects/2023/best-pizza-sf-bay-area/", "image": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSPGyTJpaRNE8ruXgkLdHkPFLVu5T7ykcJezvyYa07SUmrk7T0XaSntO19GBw&usqp=CAI&s", "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSPGyTJpaRNE8ruXgkLdHkPFLVu5T7ykcJezvyYa07SUmrk7T0XaSntO19GBw&usqp=CAI&s" } ], "knowledge": { "name": "Pizza", "summary": "Dish", "subtitle": "Dish" }, "overview": { "title": "Pizza", "kgmid": "/m/0663v" }, "snack_pack_map": { "image": "data:image/png;base64 ...", "image_base64": "data:image/png;base64 ...", "link": "https://www.google.com/search?q=pizza&sca_esv=9559f81e103ba33b&hl=en&gl=us&udm=1&lsack=fdaWadL4D5OP9u8P8LrdoAI&sa=X&ved=2ahUKEwiSq-PSneWSAxWTh_0HHXBdFyQQtgN6BAgdEAM" }, "snack_pack": [ { "cid": "2036127367591792815", "name": "Hunt Brothers Pizza", "image": "data:image/png;base64 ...", "image_base64": "data:image/png;base64 ...", "reviews_cnt": 1, "type": "Pizza", "price": "$", "work_status": "Pit stop for pizza & chicken wings", "address": "Hollister, MO", "rank": 1, "global_rank": 1 } ], "pagination": { "pages": [ { "page": 2, "start": 10, "link": "https://www.google.com/search?q=pizza&sca_esv=9559f81e103ba33b&hl=en&gl=us&ei=fdaWadL4D5OP9u8P8LrdoAI&start=10&sa=N&sstk=Af77f_chnDKNIlZ0IppYwCTGX-8AsCUfZH2WQB4kzsZIYRjsE5mqBJMEdWa84P7jgf603q2kg3ocZLtVg3UcaoXgLxAF8bRxzTc64g&ved=2ahUKEwiSq-PSneWSAxWTh_0HHXBdFyQQ8tMDegQICxAE" }, { "page": 3, "start": 20, "link": "https://www.google.com/search?q=pizza&sca_esv=9559f81e103ba33b&hl=en&gl=us&ei=fdaWadL4D5OP9u8P8LrdoAI&start=20&sa=N&sstk=Af77f_chnDKNIlZ0IppYwCTGX-8AsCUfZH2WQB4kzsZIYRjsE5mqBJMEdWa84P7jgf603q2kg3ocZLtVg3UcaoXgLxAF8bRxzTc64g&ved=2ahUKEwiSq-PSneWSAxWTh_0HHXBdFyQQ8tMDegQICxAG" }, { "page": 4, "start": 30, "link": "https://www.google.com/search?q=pizza&sca_esv=9559f81e103ba33b&hl=en&gl=us&ei=fdaWadL4D5OP9u8P8LrdoAI&start=30&sa=N&sstk=Af77f_chnDKNIlZ0IppYwCTGX-8AsCUfZH2WQB4kzsZIYRjsE5mqBJMEdWa84P7jgf603q2kg3ocZLtVg3UcaoXgLxAF8bRxzTc64g&ved=2ahUKEwiSq-PSneWSAxWTh_0HHXBdFyQQ8tMDegQICxAI" } ], "current_page": 1, "next_page": 2, "next_page_start": 10, "next_page_link": "https://www.google.com/search?q=pizza&sca_esv=9559f81e103ba33b&hl=en&gl=us&ei=fdaWadL4D5OP9u8P8LrdoAI&start=10&sa=N&sstk=Af77f_chnDKNIlZ0IppYwCTGX-8AsCUfZH2WQB4kzsZIYRjsE5mqBJMEdWa84P7jgf603q2kg3ocZLtVg3UcaoXgLxAF8bRxzTc64g&ved=2ahUKEwiSq-PSneWSAxWTh_0HHXBdFyQQ8tMDegQICxAE" }, "related": [ { "text": "Pizza wiki", "link": "https://www.google.com/search?sca_esv=9559f81e103ba33b&hl=en&gl=us&q=Pizza+wiki&sa=X&ved=2ahUKEwiSq-PSneWSAxWTh_0HHXBdFyQQ1QJ6BAhLEAE", "rank": 1, "global_rank": 17 }, { "text": "Pizza open", "link": "https://www.google.com/search?sca_esv=9559f81e103ba33b&hl=en&gl=us&q=Pizza+open&sa=X&ved=2ahUKEwiSq-PSneWSAxWTh_0HHXBdFyQQ1QJ6BAhfEAE", "rank": 2, "global_rank": 18 }, { "text": "Pizza Hut near me", "link": "https://www.google.com/search?sca_esv=9559f81e103ba33b&hl=en&gl=us&q=Pizza+Hut+near+me&sa=X&ved=2ahUKEwiSq-PSneWSAxWTh_0HHXBdFyQQ1QJ6BAheEAE", "rank": 3, "global_rank": 19 } ], "people_also_ask": [ { "question": "What's the 2 hour rule for pizza?", "question_type": "featured", "answer_source": "Green Lantern Pizza", "answer_link": "https://greenlanternpizza.com/blog/how-long-does-pizza-last/#:~:text=Sitting%20out%20at%20Room%20Temperature,-How%20long%20can&text=The%20United%20States%20Department%20of,two%20hours%20before%20tossing%20it.", "answer_display_link": "https://greenlanternpizza.com › blog › how-long-does-pi...https://greenlanternpizza.com › blog › how-long-does-pi...", "answers": [ { "type": "answer", "value": { "text": "Sitting out at Room Temperature The United States Department of Agriculture (USDA) strongly recommends following the “two-hour rule” when leaving food out, meaning you shouldn't let pizza or takeout sit at room temperature for over two hours before tossing it.Jan 29, 2025" }, "rank": 1 } ], "rank": 1, "global_rank": 7 } ] } } } }, "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestPending" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } } } } } }, "components": { "schemas": { "JobResponse": { "type": "object", "properties": { "response_id": { "description": "Defines the job id.", "type": "string", "example": "s4t7w3619285042ra9dke1m8qx" } } }, "RequestPending": { "type": "string", "example": "Request is pending" }, "NotFound": { "type": "string", "example": "Result not found" }, "Unauthorized": { "type": "string", "example": "Invalid token" } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Use your Bright Data API Key as a Bearer token in the Authorization header.\n\n**How to authenticate:**\n1. Obtain your API Key from the [Bright Data account settings](https://brightdata.com/cp/setting/users)\n2. Include the API Key in the Authorization header of your requests\n3. Format: `Authorization: Bearer YOUR_API_KEY`\n\n**Example:**\n```\nAuthorization: Bearer b5648e1096c6442f60a6c4bbbe73f8d2234d3d8324554bd...\n```\n\n> [Learn how to get your Bright Data API key](https://docs.brightdata.com/api-reference/authentication)", "bearerFormat": "API Key" } } } }