# Google Places

The Google Places API enables retrieval of Google Places search results and returns structured JSON output.

It supports local place searches for businesses, points of interest, and venues, with filters such as language, geographic location, and location targeting.

### API Setup

#### Endpoint

```
https://serp-api.netnut.io/search
```

#### Authentication

Use HTTP Basic Authentication:

```
Authorization: Basic <base64(username:password)>
```

Where `<base64(username:password)>` is the Base64-encoded string of your NetNut credentials.

#### Request Format

The request is sent as a GET request. All parameters are passed directly in the URL query string.

#### Example Request

```
https://serp-api.netnut.io/search?engine=google_places&q=coffee&gl=us&hl=en
```

### Request Parameters

| Field      | Type    | Description                                                                                                                 | Parameter Type |
| ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `engine`   | string  | Search engine to use. For this product, use `google_places`.                                                                | Required       |
| `q`        | string  | Search query or place type to search for. Example: `coffee`, `restaurants`, `pharmacies`.                                   | Required       |
| `hl`       | string  | Language of the Google Places results. Example: `en`.                                                                       | Optional       |
| `gl`       | string  | Geographic location for the search results. Example: `us`.                                                                  | Optional       |
| `uule`     | string  | Encoded location parameter used to set a precise geographic context. Overrides general country-level targeting set by `gl`. | Optional       |
| `location` | string  | Plain-text location string used to target results to a specific city or region. Example: `New York, NY`.                    | Optional       |
| `udm`      | integer | Google search mode parameter. Set to `1` to enable the Places results mode.                                                 | Optional       |
| `rawHtml`  | integer | Controls whether raw HTML is returned. `1` = return parsed JSON + HTML, `2` = return HTML only.                             | Optional       |

***

### Code Examples

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET "https://serp-api.netnut.io/search?engine=google_places&q=coffee&gl=us&hl=en" \
  -u "username:password"
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
from base64 import b64encode

headers = {
    "Authorization": "Basic " + b64encode(b"username:password").decode()
}

params = {
    "engine": "google_places",
    "q": "coffee",
    "gl": "us",
    "hl": "en"
}

response = requests.get("https://serp-api.netnut.io/search", headers=headers, params=params)
print(response.json())
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const username = "username";
const password = "password";

const params = new URLSearchParams({
  engine: "google_places",
  q: "coffee",
  gl: "us",
  hl: "en"
});

const response = await fetch(`https://serp-api.netnut.io/search?${params}`, {
  method: "GET",
  headers: {
    "Authorization": "Basic " + Buffer.from(`${username}:${password}`).toString("base64")
  }
});

const data = await response.json();
console.log(data);
```

{% endtab %}
{% endtabs %}

***

### Response Format

The Google Places API returns structured JSON.

No HTML is returned by default. When `rawHtml=1`, the response includes both the parsed JSON and the raw HTML. When `rawHtml=2`, the response returns only the raw HTML.

#### Response Fields

**Top-Level Fields**

| Field          | Type   | Description                                                                                                                                                     |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`          | string | The full Google Search URL used to retrieve results.                                                                                                            |
| `general`      | object | Metadata about the search request and result. See [General Fields](https://claude.ai/chat/a19cac85-f480-4b5a-a6bd-e68cbbf4d011#general-fields).                 |
| `input`        | object | Details about the original request. See [Input Fields](https://claude.ai/chat/a19cac85-f480-4b5a-a6bd-e68cbbf4d011#input-fields).                               |
| `localResults` | array  | List of local place results returned by the search. See [Local Result Fields](https://claude.ai/chat/a19cac85-f480-4b5a-a6bd-e68cbbf4d011#local-result-fields). |
| `pagination`   | object | Pagination metadata for the response. See [Pagination Fields](https://claude.ai/chat/a19cac85-f480-4b5a-a6bd-e68cbbf4d011#pagination-fields).                   |
| `html`         | string | Raw HTML of the Google Search results page. Only present when `rawHtml=1` or `rawHtml=2`.                                                                       |

***

**General Fields**

| Field          | Type    | Description                                                      |
| -------------- | ------- | ---------------------------------------------------------------- |
| `searchEngine` | string  | The search engine used. Always `google_places` for this product. |
| `resultsCount` | integer | Total number of results returned.                                |
| `searchTime`   | float   | Time taken to complete the search, in seconds.                   |
| `language`     | string  | Language of the results, as set by the `hl` parameter.           |
| `device`       | string  | Device type used for the search (e.g., `desktop`).               |
| `searchType`   | string  | Type of search performed (e.g., `text`).                         |
| `pageTitle`    | string  | Title of the Google Search results page.                         |
| `timestamp`    | string  | ISO 8601 timestamp of when the search was performed.             |
| `render`       | boolean | Whether page rendering was used to retrieve results.             |

***

**Input Fields**

| Field         | Type   | Description                            |
| ------------- | ------ | -------------------------------------- |
| `originalUrl` | string | The original URL submitted to the API. |
| `jobId`       | string | Unique identifier for the search job.  |

***

**Local Result Fields**

| Field          | Type    | Description                                           |
| -------------- | ------- | ----------------------------------------------------- |
| `cid`          | string  | Google's Customer ID for the place, if available.     |
| `place_id`     | string  | Unique identifier for the place.                      |
| `name`         | string  | Name of the place.                                    |
| `sponsored`    | boolean | Whether the result is a sponsored listing.            |
| `image`        | string  | URL of the place's image.                             |
| `rating`       | float   | Average star rating of the place.                     |
| `reviews_cnt`  | string  | Number of reviews for the place.                      |
| `reviews_link` | string  | URL to the place's reviews on Google.                 |
| `price`        | string  | Price range indicator (e.g., `$1-10`).                |
| `type`         | string  | Category or type of the place (e.g., `Coffee shop`).  |
| `open_state`   | string  | Current open/closed status and next opening time.     |
| `latitude`     | float   | Latitude coordinate of the place.                     |
| `longitude`    | float   | Longitude coordinate of the place.                    |
| `top_review`   | string  | Snippet from the top-rated review.                    |
| `address`      | string  | Address of the place.                                 |
| `phone`        | string  | Phone number of the place, if available.              |
| `tags`         | array   | List of tags or attributes associated with the place. |
| `rank`         | integer | Position of the result within the current page.       |
| `global_rank`  | integer | Position of the result across all pages.              |

***

**Pagination Fields**

| Field         | Type    | Description                             |
| ------------- | ------- | --------------------------------------- |
| `currentPage` | integer | The current page number of the results. |

***

#### Example JSON Response

```json
{
  "url": "https://www.google.com/search?gl=US&hl=en&q=coffee&udm=1&uule=w+CAIQICINVW5pdGVkIFN0YXRlcw",
  "general": {
    "searchEngine": "google_places",
    "resultsCount": 41,
    "searchTime": 0.35,
    "language": "en",
    "device": "desktop",
    "searchType": "text",
    "pageTitle": "coffee - Google Search",
    "timestamp": "2026-04-20T09:17:32.522961567Z",
    "render": false
  },
  "input": {
    "originalUrl": "https://www.google.com/search?gl=US&hl=en&q=coffee&udm=1&uule=w+CAIQICINVW5pdGVkIFN0YXRlcw",
    "jobId": "5ae9e608-0d7c-417d-897a-e0f3dab53be7"
  },
  "localResults": [
    {
      "cid": "",
      "place_id": "6424352471498379864",
      "name": "Cattle Mtn Coffee",
      "sponsored": false,
      "image": "https://lh3.googleusercontent.com/gps-cs-s/...",
      "rating": 5,
      "reviews_cnt": "52",
      "reviews_link": "https://www.google.com/viewer/place?...",
      "price": "$10–20",
      "type": "Coffee shop",
      "open_state": "Closed · Opens 6 AM Thu",
      "latitude": 37.669144,
      "longitude": -106.63993,
      "top_review": "\"Great coffee, amazing breakfast sandwich, all for a total of $13.\"",
      "address": "South Fork, CO",
      "phone": "",
      "tags": [],
      "rank": 1,
      "global_rank": 1
    },
    {
      "cid": "",
      "place_id": "18102343801949734750",
      "name": "TRY Coffee",
      "sponsored": false,
      "image": "https://lh3.googleusercontent.com/gps-cs-s/...",
      "rating": 4.6,
      "reviews_cnt": "156",
      "reviews_link": "https://www.google.com/viewer/place?...",
      "price": "$1–10",
      "type": "Coffee shop",
      "open_state": "Closed · Opens 6:30 AM Mon",
      "latitude": 21.29283,
      "longitude": -157.85295,
      "top_review": "\"Unique coffees, excellent craft and service, and a lovely outdoor lanai.\"",
      "address": "Honolulu, HI",
      "phone": "",
      "tags": [],
      "rank": 2,
      "global_rank": 2
    }
  ],
  "pagination": {
    "currentPage": 1
  },
  "html": "<!doctype html><html ..."
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.netnut.io/netnut-documentation/netnut-scraper-apis/serp-api/google-scraper/google-places.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.