NAV Navbar
shell

Introduction

Welcome to the Zenserp API!

You can view code examples in the dark area to the right.

Authentication

To authorize, you can use the following ways:

curl "https://app.zenserp.com/api/search"
  -H "apikey: APIKEY"
curl "https://app.zenserp.com/api/search?apikey=APIKEY"
curl "https://app.zenserp.com/api/search" -F "apikey=APIKEY"

Zenserp uses API keys to allow access to the API. You can register a new API key at our developer portal.

Zenserp looks for the API key in a header that looks like the following (recommended, works with all requests):

apikey: APIKEY

For GET requests you can also use a URL parameter:

ex. https://app.zenserp.com/api/search?apikey=APIKEY

For POST requests you can also use a form field:

apikey=APIKEY

Status

curl "https://app.zenserp.com/api/status"
  -H "apikey: APIKEY"

The above command returns JSON structured like this:

{
  "remaining_requests": 1500
}

This endpoint retrieves the number of remaining requests.

Any of the requests below also return a x-ratelimit-remaining header with the number of the remaining requests.

HTTP Request

GET https://app.zenserp.com/api/status

Get a SERP

curl "https://app.zenserp.com/api/search?q=Pied+Piper&location=United+States&search_engine=google.com&language=English" -H "apikey: APIKEY"
curl "https://app.zenserp.com/api/search" -F "q=Pied Piper" -F "location=United States" -F "search_engine=google.com" -F "language=English" -H "apikey: APIKEY"

The above command returns JSON structured like this:

{
  "q": "Pied Piper",
  "domain": "google.com",
  "location": "United States",
  "language": "English",
  "url": "https://www.google.com/search?q=Pied%20Piper&num=100&hl=en&gl=US&gws_rd=cr&ie=UTF-8&oe=UTF-8&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc",
  "total_results": 17100000,
  "auto_correct": "",
  "auto_correct_type": "",
  "results": []
}

The results array consists of:

Name of a field Type Description
      left array results array from the main body of the SERP
here you can find the following elements: organic, paid, top_stories, people_also_ask, local_pack, carousel, images, video, map, twitter, app, shopping, google_flights, jobs, answer_box, related_search, related
            ‘paid’ element in SERP    
            type string type of element = ‘paid’
            position integer position in the SERP
            url string relevant URL of the Ad element
            title string snippet header of the Ad element
            snippet_row1 string first snippet row in the element
            snippet_row2 string second snippet row in the element
            links array links which are included to the SERP element snippet
                  url string relevant URL
                  title string snippet header
                  snippet string snippet
            stat array statistics
                  rating integer/float rating
the popularity rate based on reviews and displayed in the SERPs
                  rating_max integer maximum value for a rating
            ‘organic’ element in SERP    
            type string type of element = ‘organic’
            position integer position in the SERP
            featured_snippet boolean indicates whether the element is a featured_snippet
            image boolean indicates whether the element has an image
            video boolean indicates whether the element has a video
            url string relevant URL in the SERP
            title string snippet header in the SERP
            snippet string snippet in the SERP
            snippet_extra string additional snippet in the SERP
ratings, price, author, etc
            links array links which are included to the SERP element snippet
                  url string relevant URL
                  title string snippet header
                  snippet string snippet
            stat array statistics
                  rating integer/float rating
the popularity rate based on reviews and displayed in the SERPs
                  rating_max integer maximum value for a rating
            ‘featured snippet’ element in SERP    
            type string type of element = ‘featured_snippet’
            position integer position in the SERP
            url string relevant URL in the SERP
            title string snippet header in the SERP
            snippet string snippet in the SERP
            table array array of elements
                  table_header array array of table header strings
                  table_data array array of table row strings
            ‘top stories’ element in SERP    
            type string type of element = ‘top_stories’
            position integer position in the SERP
            items array array of items
                  url string relevant URL of the element
                  title string title of the element
                  date string date of the element
                  source string source of the element
            ‘answer box’ element in SERP    
            type string type of element = ‘answer_box’
            position integer position in the SERP
            text array array of the string with text elements
            links array array of URLs
                  url string relevant URL
                  anchor string anchor for the URL
            ‘people also ask’ element in SERP    
            type string type of element = ‘people_also_ask’
            position integer position in the SERP
            items array array of the string with text elements
            ‘app’ element in SERP    
            type string type of element = ‘app’
            position integer position in the SERP
            items array array of applications
                  url string relevant URL of the application
                  title string title of the application
                  snippet string snippet of the application
                  price string price for the application
            ‘carousel’ element in SERP    
            type string type of element = ‘carousel’
            position integer position in the SERP
            title string title of carousel
            items array array of items
                  title string title of the element
            ‘local pack’ element in SERP    
            type string type of element = ‘local_pack’
            position integer position in the SERP
            url string relevant URL of the element
            title string snippet header of the element
            snippet string snippet of the element
            rating integer/float rating
the popularity rate based on reviews and displayed in the SERPs
            rating_type string measurement units
shows which measurement units are used in the rating field
there are two possible options: stars, percents
            rating_max integer maximum value for a rating
            paid boolean paid advertisement
            ‘map’ element in SERP    
            type string type of element = ‘map’
            position integer position in the SERP
            url string relevant URL
            title string snippet header in the SERP
            ‘twitter’ element in SERP    
            type string type of element = ‘twitter’
            position integer position in the SERP
            url string URL of the twitter homepage
            title string title of the twitter
            items array array of items
                  url string URL of the tweet
                  tweet string tweet message
                  date string date of tweet message
            ‘shopping’ element in SERP    
            type string type of element = ‘shopping’
            position integer position in the SERP
            title string title of the product in google shopping
            items array array of items
                  title string title of the product
                  url string URL of the product
                  price string price of the product
                  source string source
            ‘video’ element in SERP    
            type string type of element = ‘video’
            position integer position in the SERP
            items array array of URL videos
                  url string URL of the video
                  title string title of the video
                  source string source of the video
            ‘images’ element in SERP    
            type string type of element = ‘images’
            position integer position in the SERP
            url string URL of the image
            title string title of the image
            position integer position in the SERP
            items array array of URL images
                  url string URL of the image
                  alt string alt attribute
            ‘google flights’ element in SERP    
            type string type of element = ‘google_flights’
            position integer position in the SERP
            url string URL of current tickets
            title string title
            position integer position in the SERP
            items array array of URLs
                  url string URL of this ticket
                  description string description
            ‘jobs’ element in SERP    
            type string type of element = ‘jobs’
            position integer position in the SERP
            url string URL of current jobs
            title string title
            position integer position in the SERP
            items array array of vacancies
                  url string URL of this vacancy
                  snippet string snippet
                  author string author
                  date string date of this vacancy
                  type string type of work
            ‘related search’ element in SERP    
            type string type of element = ‘related_search’
            position integer position in the SERP
            title string title of the related search element
            items array array of related keywords
            ‘related’ element in SERP    
            type string type of element = ‘related’
            position integer position in the SERP
            items array array of related keywords
      right array results array from the right side of the SERP with extra elements
here you can find the following elements: knowledge_graph, google review
            ‘knowledge graph’ element in SERP    
            type string type of element = ‘knowledge_graph’
            position integer position in the SERP
            url string relevant URL in the SERP
            title string header in the SERP
            subtitle string subtitle in the SERP
            description string text of knowledge graph
            parts array array of knowledge graph text items
            card_id string the knowledge graph id
            ‘google review’ element in SERP    
            type string type of element = ‘google_review’
            position integer position in the SERP
            reviews_count integer number of results in the reviews list
            place_id string place ID

HTTP Request

GET https://app.zenserp.com/api/search

Query Parameters (via URL or Header)

Parameter Description Default
q The keyword to query None (required)
location The location used in the query United States
language The language of the search engine English
search_engine The url of the search engine to query google.com

HTTP Request

POST https://app.zenserp.com/api/search

Query Parameters

Parameter Description Default
q The keyword to query None (required)
location The location used in the query United States
language The language of the search engine English
search_engine The url of the search engine to query google.com

Errors

The Zenserp API uses the following error codes:

HTTP Error Code Meaning
403 Forbidden -- API key is wrong, you don't have enough requests or you don't have enough rights to access it.
404 Not Found -- The route was not found.
500 Internal Server Error -- See below.

The API returns errors in this template:

{
    "errors": [{
        "search_engine": "Search engine not valid."
    }]
}