Skip to main content
See also the API reference for more detail.

​
Usage

‘s search service delivers all organic and paid Google results reliably, as structured or raw data. The service has a RESTful interface that accepts GET requests at https://‍/search. Searches can be localized with geotargeting parameters. They’re performed live by default or optionally queued for subsequent retrieval. Live searches take an average of a few seconds but may require multiple retries, in which case up to 120 seconds is allocated per API call.

​
Authentication

You can access the service by including your secret API token in an Authorization header: 
Authorization: Bearer [API token here]
Here’s an example request that uses the common Curl command: 
$ curl -H "Authorization: Bearer $AGENT_FIRST_TOKEN" \
  'https://api.agentfirst.dev/search'\
  '?terms=foo+bar+baz'

​
Search parameters

Besides the geotargeting and scheduling parameters linked above, required and optional search parameters can be added in a standard query string. The keys and values supports are as follows:
KeyRequiredValue
terms✅The broad or exact word or phrase to query (e.g., foo bar baz or "foo bar baz"); the terms require form or URL encoding (with any space character being replaced by a + character or %20 sequence)
serps⬜The number of results pages to retrieve, from 1 to 10 inclusive; 1 is the default count
size⬜The number of results per page to retrieve, from 0 to 100 inclusive; page size is unset by default
offset⬜The number of initial results to skip, from 0 to 100 inclusive; results aren’t offset by default
uule⬜The proprietary encoded string for emulating the location to search from; if possible, the actual location will be searched from not emulated; location emulation is unused by default
language⬜The commonly spelled name, two-letter ISO code, or Google code of the language to search in (these names and codes are case insensitive but required to include form- or URL-encoded spaces and punctuation marks); the language is unset by default
format⬜The format to output to, html or json (see the section below); html is the default format
expiration⬜The maximum age of cached results in days to accept, where 0 will disable caching; 1 is the default number of days
subaccount⬜Any unique identifier of up to 255 characters (regardless of character encoding); will bill calls made from subaccounts separately

​
Response format

Search results are returned as rendered HTML or structured JSON.

​
HTML

If you request multiple results pages that don’t feature infinite scrolling, the HTML of each page will be separated from the next by an empty line (\n\n).

​
JSON

If you set the output to JSON, your results will be parsed into nested objects. 
{
               "query": "foo",
  "approxResultsCount": 255000000,
        "resultsCount": 43,
             "results": [{
                                "type": "organic",
                                "page": 1,
                             "section": "main",
                             "feature": 1,
                            "position": 1,
                                 "url": "https://foofighters.com/",
                               "title": "Foo Fighters",
                                "site": "Foo Fighters",
                          "visibleUrl": "https://foofighters.com",
                                "date": null,
                             "snippet": "Official website of Foo Fighters.",
                              "rating": null,
                               "votes": null,
                           "sitelinks": [{
                                          "position": 1,
                                               "url": "https://foofighters.com/tour-dates/",
                                             "title": "Tour Dates"
                                        }, {
                                          "position": 2,
                                               "url": "https://shop.foofighters.com/",
                                             "title": "Shop"
                                        }, {
                                          "position": 3,
                                               "url": "https://foofighters.com/news/",
                                             "title": "News"
                                        }, {
                                          "position": 4,
                                               "url": "https://foofighters.com/news/a-message-from-the-hawkins-family/",
                                             "title": "A Message from The Hawkins..."
                                        }],
                              "images": []
                        }, {
                              "type": "also-asked",
                              "page": 1,
                           "section": "main",
                           "feature": 2,
                          "position": 1,
                          "question": "What does foo mean?",
                            "answer": {
                                            "heading": null,
                                        "description": "Foo (pronounced FOO) is a term used by programmers as a placeholder for a value that can change, depending on conditions or on information passed to the program.",
                                               "date": null,
                                                "url": "https://www.techtarget.com/searchapparchitecture/definition/foo-in-software-programming#:~:text=Foo%20(pronounced%20FOO)%20is%20a,information%20passed%20to%20the%20program.",
                                              "title": "What Is Foo in Software Programming? Definition from ...",
                                               "site": "TechTarget",
                                         "visibleUrl": "https://www.techtarget.com › searchapparchitecture › foo-..."
                                      }
                        }, {
                              "type": "also-asked",
                              "page": 1,
                           "section": "main",
                           "feature": 2,
                          "position": 2,
                          "question": "What is the English word Foo?",
                            "answer": {
                                            "heading": null,
                                        "description": "noun (1) ˈfü(ˌ)fü plural -s. slang. : fool, ninny.",
                                               "date": null,
                                                "url": "https://www.merriam-webster.com/dictionary/foo-foo#:~:text=1%20of%202-,noun%20(1),%3A%20fool%2C%20ninny",
                                              "title": "Foo-foo Definition & Meaning - Merriam-Webster",
                                               "site": "Merriam-Webster",
                                         "visibleUrl": "https://www.merriam-webster.com › dictionary › foo-foo"
                                      }
                        }, {
                              "type": "also-asked",
                              "page": 1,
                           "section": "main",
                           "feature": 2,
                          "position": 3,
                          "question": "Why do Hispanics say \"foo\"?",
                            "answer": {
                                            "heading": null,
                                        "description": "Foo is the diminutive of “fool” (because that extra “L” makes it far too lengthy). It is a term of endearment and part of the common Southern California Latino vernacular. The use of “fool” is foreign to others. It can be taken as a challenge, especially if the wrong tone or cadence are used.",
                                               "date": "Apr 11, 2022",
                                                "url": "https://ouresquina.com/2022/a-head-nod-to-the-foos-friendly-or-not/#:~:text=Foo%20is%20the%20diminutive%20of,tone%20or%20cadence%20are%20used.",
                                              "title": "A head nod to the Foos, friendly or not - Our Esquina",
                                               "site": "Our Esquina",
                                         "visibleUrl": "https://ouresquina.com › a-head-nod-to-the-foos-friendly-..."
                                      }
                        }, {
                          "[Remaining “People also ask” results here]"
                        }, {
                                "type": "organic",
                                "page": 1,
                             "section": "main",
                             "feature": 3,
                            "position": 1,
                                 "url": "https://en.wikipedia.org/wiki/Foo_Fighters",
                               "title": "Foo Fighters",
                                "site": "Wikipedia",
                          "visibleUrl": "https://en.wikipedia.org › wiki › Foo_Fighters",
                                "date": null,
                             "snippet": "Foo Fighters is an American rock band formed in Seattle in 1994. Founded as a one-man project by former Nirvana drummer Dave Grohl, the lineup now consists ...",
                              "rating": null,
                               "votes": null,
                           "sitelinks": [],
                              "images": [{
                                          "position": 1,
                                            "source": "[Image data here]",
                                               "alt": "foo from en.wikipedia.org"
                                        }]
                        }, {
                                "type": "organic",
                                "page": 1,
                             "section": "main",
                             "feature": 3,
                            "position": 2,
                                 "url": "https://www.merriam-webster.com/dictionary/foo",
                               "title": "Foo Definition & Meaning",
                                "site": "Merriam-Webster",
                          "visibleUrl": "https://www.merriam-webster.com › dictionary › foo",
                                "date": null,
                             "snippet": "The meaning of FOO is Scottish variant of how.",
                              "rating": null,
                               "votes": null,
                           "sitelinks": [],
                              "images": [{
                                          "position": 1,
                                            "source": "[Image data here]",
                                               "alt": "foo from www.merriam-webster.com"
                                        }]
                        }, {
                               "type": "top-story",
                               "page": 1,
                            "section": "main",
                            "feature": 4,
                           "position": 1,
                                "url": "https://nypost.com/2024/09/10/entertainment/foo-fighters-dave-grohl-reveals-he-cheated-welcomed-baby-outside-of-marriage/",
                          "publisher": "New York Post",
                           "headline": "Foo Fighters’ Dave Grohl reveals he cheated on his wife, welcomed baby ‘outside’ of his marriage",
                               "date": "2 hours ago",
                              "image": "[Image data here]",
                        }, {
                               "type": "top-story",
                               "page": 1,
                            "section": "main",
                            "feature": 4,
                           "position": 2,
                                "url": "https://www.mirror.co.uk/3am/celebrity-news/breaking-dave-grohl-admits-cheating-33640293",
                          "publisher": "The Mirror",
                           "headline": "Foo Fighters' Dave Grohl admits cheating on wife as he reveals fathering secret baby",
                               "date": "3 hours ago",
                              "image": "[Image data here]",
                        }, {
                               "type": "top-story",
                               "page": 1,
                            "section": "main",
                            "feature": 4,
                           "position": 3,
                                "url": "https://www.nbcnews.com/news/us-news/dave-grohl-announces-become-father-baby-born-marriage-rcna170498",
                          "publisher": "NBC News",
                           "headline": "Dave Grohl announces he's become the father of a baby born outside his marriage",
                               "date": "1 hour ago",
                              "image": "[Image data here]",
                        }, {
                          "[Remaining “Top stories” results here]"
                        }, {
                          "[Remaining organic results here]"
                        }, {
                              "type": "also-searched",
                              "page": 1,
                           "section": "bottom",
                           "feature": 1,
                          "position": 1,
                               "url": "https://www.google.com/search?sca_esv=7f94d02cc2bb7a85&sca_upv=1&q=Dave+Grohl&stick=H4sIAAAAAAAAAOMwVGI0-MXIsIGF4RULFxeHfq6-gZGFafIrFm4uThDHMKUiLRkulWRYVQXnpJQVFsI5llm5FnCOWW6WCZxjbpyOUGZSlFyEMNvIoKgKzksxtDTOWMTK5ZJYlqrgXpSfkXOLTZKh-2mPcWB8SME7leaDUof2LHlq8nPd7DLvVYs4xAJS8wtyUhUSc4rzFYpTE4uSMxTS8osAI_QNztIAAAA&sa=X&ved=2ahUKEwi1vO_B_5yIAxV8ElkFHRySAR4Qs9oBKAB6BAhkEAk",
                             "query": "Dave Grohl"
                        }, {
                              "type": "also-searched",
                              "page": 1,
                           "section": "bottom",
                           "feature": 1,
                          "position": 2,
                               "url": "https://www.google.com/search?sca_esv=7f94d02cc2bb7a85&sca_upv=1&q=Taylor+Hawkins&stick=H4sIAAAAAAAAAOMwVGI0_MXIsIGF4RULFxeHfq6-gZGFafIrFm4uThDHMKUiLRkulWRYVQXnpJQVFsI5llm5FnCOWW6WCZxjbpyOUGZSlFyEMNvIoKgKzksxtDTOWMTKF5JYmZNfpOCRWJ6dmVd8i02Softpj3FgfEjBO5Xmg1KH9ix5avJz3ewy71WLOMQCUvMLclIVEnOK8xWKUxOLkjMU0vKLAL7S69nWAAAA&sa=X&ved=2ahUKEwi1vO_B_5yIAxV8ElkFHRySAR4Qs9oBKAB6BAhkEA4",
                             "query": "Taylor Hawkins"
                        }, {
                              "type": "also-searched",
                              "page": 1,
                           "section": "bottom",
                           "feature": 1,
                          "position": 3,
                               "url": "https://www.google.com/search?sca_esv=7f94d02cc2bb7a85&sca_upv=1&q=Nirvana+(band)&stick=H4sIAAAAAAAAAOMwVGI0-sXIsIGF4RULFxeHfq6-gZGFafIrFm4uThDHMKUiLRkulWRYVQXnpJQVFsI5llm5FnCOWW6WCZxjbpyOUGZSlFyEMNvIoKgKzksxtDTOWMTK55dZVJaYl6igkZSYl6J5i02Softpj3FgfEjBO5Xmg1KH9ix5avJz3ewy71WLOMQCUvMLclIVEnOK8xWKUxOLkjMU0vKLAJ7k8YDWAAAA&sa=X&ved=2ahUKEwi1vO_B_5yIAxV8ElkFHRySAR4Qs9oBKAB6BAhkEBM",
                             "query": "Nirvana"
                        }, {
                          "[Remaining “People also search for” results here]"
                        }]
}

​
Additional examples

​
Omission

$ curl -H "Authorization: Bearer $AGENT_FIRST_TOKEN" \
  'https://api.agentfirst.dev/search'\
  '?terms=vpn+comparison'\
  '&size=100'\
  '&offset=20'

​
Accounting

$ curl -H "Authorization: Bearer $AGENT_FIRST_TOKEN" \
  'https://api.agentfirst.dev/search'\
  '?terms=jargon+file'\
  '&subaccount=fubarco+systems'