List Searches

8 min

List Searches

You can List the Searches for a Batch by making making a HTTP GET request to the /batches/BATCH_ID/searches/PAGE endpoint (where BATCH_ID is the id of the Batch to get Searches for, and PAGE is the page of Searches to get).

The /batches/BATCH_ID/searches/PAGE endpoint returns the Searches for a Batch in pages of 1000 Searches per page. Pages start at 1 . You can find out how many pages a Batch has by inspecting the searches_page_count field returned from the Get Batch endpoint.

VALUE SERP also provides two more endpoints to allow you to retrieve a download link for all Searches in a Batch, in either JSON or CSV format.

List Searches by Page

GET /batches/BATCH_ID/searches/PAGE

In the example below we List page 1 of the Searches for the Batch with id=123456 :

https://api.valueserp.com/batches/123456/searches/1?api_key=demo

VALUE SERP responds with the following JSON showing all the Searches on page 1 of the Batch:

{
  "request_info": {
    "success": true
  },
  "batch_id": "123456",
  "searches_page_current": 1,
  "searches_page_count": 1,
  "searches": [
    {
      "q": "mcdonalds",
      "location": "United States",
      "search_type": "images",
      "custom_id": "MyCustomID_001",
      "id": "ABCDEFGHIJKLMNOP"
    }
  ]
}

Get JSON Download Links

GET /batches/BATCH_ID/searches/json

In the example below we retrieve download links for all Searches for Batch with id=123456 in JSON format:

https://api.valueserp.com/batches/123456/searches/json?api_key=demo

VALUE SERP responds with the following JSON detailing the total number of Searches searches_total_count , the total number of pages searches_page_count and a JSON file download_link for each page:

{
  "request_info": {
    "success": true
  },
  "batch_id": "123456",
  "searches_total_count": 1,
  "searches_page_count": 1,
  "download_links": {
    "pages": [
      "https://searches.valueserp.com/Batch_Searches_123456_Page_1.json"
    ]
  }
}

Get CSV Download Links

GET /batches/BATCH_ID/searches/csv

In the example below we retrieve download links for all Searches for Batch with id=123456 in CSV format:

https://api.valueserp.com/batches/123456/searches/csv?api_key=demo

VALUE SERP responds with the following JSON detailing the total number of Searches searches_total_count , the total number of pages searches_page_count and a CSV file download_link for each page:

{
  "request_info": {
    "success": true
  },
  "batch_id": "123456",
  "searches_total_count": 1,
  "searches_page_count": 1,
  "download_links": {
    "pages": [
      "https://searches.valueserp.com/Batch_Searches_123456_Page_1.csv"
    ]
  }
}

Next Steps Listing Result Sets Getting Result Sets