Accessing the Google Custom Search API using PowerShell

Jump to page sections

In this article I demonstrate how to use the Google Custom Search Engine (CSE) API v1 from PowerShell. PowerShell version 3 is required for getting the Invoke-RestMethod cmdlet.

Currently (March 2013), Google allows you up to 100 free searches per day. This is based on v1 of the JSON/REST API.

You will have to continue your search if you're stuck with PowerShell version 2 or earlier; there are some code examples for web requests, REST and JSON out there (I know Joel Bennett has posted some stuff on poshcode.org).

See this article for how to access the Microsoft Cognitive Services Bing Web Search API (v5).

Requirements

You will need to get an API key from Google and to set up a custom search engine. I set up the search engine through my Google AdSense account under "My ads" - "Search" - "Custom Search Engines" and set it up to look something like this:

I'm basing these examples on the documentation Google provides here.

Example

Create a Proper Query String

Firstly, it'll come in handy to create a little function to turn provided search terms into a proper URL-encoded query string for Google. This should do:

function Get-GoogleCSEQueryString {
    
    param([string[]] $Query)
    
    Add-Type -AssemblyName System.Web # To get UrlEncode()
    $QueryString = ($Query | %{ [Web.HttpUtility]::UrlEncode($_)}) -join '+'
    
    # Return the query string
    $QueryString
    
}

Get that function into your current scope (put in file and dot-source, or just paste it into the console).

Providing Credentials

You can do this however you want. I created a file that I dot-source to get the (global) variables $GoogleCSEAPIKey and $GoogleCSEIdentifier which I then use in the query string passed to Invoke-RestMethod later.

Get the credentials:

PS C:\> . E:\temp\GoogleCSECreds.ps1
Set the two global variables $GoogleCSEAPIKey and $GoogleCSEIdentifier

GoogleCSECreds.ps1 contains two variable assignments and the message:

$global:GoogleCSEAPIKey = "API Key here..."
$global:GoogleCSEIdentifier = "The custom search engine/publisher ID here"

'Set the two global variables $GoogleCSEAPIKey and $GoogleCSEIdentifier'

Of course, it doesn't matter what you name the variables or how you do this so long as you get the credentials in the query.

Constructing the URI

I try to be as random as humanly possible when I think of examples in my articles, and now I'm using "fast cars" as the search query, even though I generally speaking don't give two turds about cars.

PS C:\> $SearchString = 'fast cars'

PS C:\> $QueryString = Get-GoogleCSEQueryString $SearchString

PS C:\> $Uri = "https://www.googleapis.com/customsearch/v1?key=$GoogleCSEAPIKey&cx=$GoogleCSEIdentifier&q=$QueryString"

Getting Search Results

Then we can whip out Invoke-RestMethod and get some results. The structure of the returned JSON response (converted to a custom PowerShell object) from Google is documented here.

PS C:\> $Results = Invoke-RestMethod -Uri $Uri

PS C:\> $Results | Select -Expand Items | Select -First 1 title, snippet, link | fl

title : FAST CARS! - YouTube snippet : Mar 28, 2006 ... NY to LA fun run 2004 called Mischief 3000 don't deny. link : http://www.youtube.com/watch?v=GQcrusOSiUY

That's it. Play around with the $Results object (pipe it to Get-Member) and get what you want from it. There's more information on Google's site about optional parameters, etc. I considered writing a wrapper module for Google CSE, but decided instead to save myself the time and just provide an example.