# Google Place Details

`POST https://api.serpkite.com/v1/place` · Credits: 1 per place

One place by place_id, cid or fid (or a Yandex Maps oid): address, country, time zone, structured weekly hours, phones, website, description and photos.

The full Google Maps listing of one place, identified by `place_id`, `cid` or `fid` (all three come back from [/v1/maps](https://serpkite.com/docs/endpoints/maps) and [/v1/places](https://serpkite.com/docs/endpoints/places)): address, country, coordinates, time zone, categories, opening hours as text and as structured `weekly_hours`, website, local and international phone, rating, description and up to 10 photos, in `language`.

`results` holds the place, or is empty (not charged) when no place has that identifier. A `max_age` cache hit costs half, and so does the place in a [batch](https://serpkite.com/docs/batch).

## Request body

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `place_id` | string |  | Google place ID (`"ChIJ…"`). One of `place_id`, `cid` or `fid` is required; `place_id` wins, then `fid`, then `cid`. |
| `cid` | string |  | Place and reviews: Google customer ID of the place (decimal). |
| `fid` | string |  | Place and reviews: Google feature ID of the place ("0x…:0x…"). |
| `oid` | string |  | Yandex Maps organisation ID (digits): looks the place up on Yandex Maps instead of Google, and implies `engine=yandex`. Not combined with `place_id`, `cid` or `fid`. See [Yandex Maps](https://serpkite.com/docs/providers#yandex-maps). |
| `country` | string | `us` | Country code (ISO 3166-1 alpha-2): Google's regional view of the listing. |
| `language` | string | `en` | Language of the address, categories, hours and description (en, ru, de…). |
| `format` | string | `json` | Response format. markdown is LLM-ready prose; compact is JSON with only the fields agents need. One of: `json`, `compact`, `markdown`. |
| `fields` | string |  | Comma-separated projection, e.g. results.title,results.link,knowledge_graph. Cuts tokens. |
| `max_age` | integer |  | Accept a cached result up to this many seconds old. Cache hits cost 50% of the credits. |

## Example request

cURL:

```bash
curl https://api.serpkite.com/v1/place \
  -H "Authorization: Bearer $SERPKITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"place_id":"ChIJ94DTm1cDdkgRibmgxzXy2EQ","country":"gb"}'
```

TypeScript:

```ts
import { SerpKite } from "serpkite";

const sk = new SerpKite(); // reads SERPKITE_API_KEY
const res = await sk.place({ place_id: "ChIJ94DTm1cDdkgRibmgxzXy2EQ", country: "gb" });
console.log(res.results[0].title, res.meta.credits_used);
```

Python:

```python
from serpkite import SerpKite

sk = SerpKite()  # reads SERPKITE_API_KEY
res = sk.place(place_id="ChIJ94DTm1cDdkgRibmgxzXy2EQ", country="gb")
print(res.results[0].title, res.meta.credits_used)
```

## Response fields

| Field | Type | Description |
| --- | --- | --- |
| `request` | object | The normalised request, with defaults filled in: `endpoint`, `engine`, `q`, `country`, `language`, `location`, `num`, `page`, `device`, `autocorrect`… |
| `results[]` | array | The place (one item): `title`, `address`, `country` (ISO code, upper case), `latitude`, `longitude`, `timezone` (IANA), `rating`, `rating_count`, `price_level`, `type`, `types[]`, `website`, `phone_number`, `international_phone_number`, `opening_hours`, `weekly_hours`, `description`, `thumbnail_url`, `google_maps_url`, `place_id`, `cid`, `fid` (with `engine=yandex`: `oid` and `yandex_maps_url` instead of the Google IDs and URL). Fields the map doesn't show for a place are absent. |
| `results[].opening_hours` | object | Hours as Google displays them, keyed by English weekday, in `language`: `{"Monday": "7:30 am–6 pm", "Sunday": "Closed"}`. |
| `results[].weekly_hours` | object | The same hours as data: `monday` … `sunday`, each a list of `{open, close}` local times (`HH:MM`, 24-hour, in `timezone`). Closed is `[]`, open 24 hours is `[{"open":"00:00","close":"24:00"}]`, a midnight close is `"24:00"`, and an interval past midnight has `next_day: true` (17:30–03:00). Days Google doesn't list are absent. |
| `results[].photos[]` | array | Up to 10 photos: `url` (public, fetchable server-side without cookies; at most 1600 px on the long side), `width`, `height`, `source` (`business` or `visitor`, when Google says). |
| `meta` | object | `request_id`, `credits_used`, `cached`, `cached_at`, `engine` (the provider that answered), `route` (provider attempts, see [Search providers](https://serpkite.com/docs/providers)), `latency_ms`, `parse_quality` (`ok`, `partial`, `empty`), `resolved_urls`; `llm` (`provider`, `model`, `input_tokens`, `output_tokens`) and `warnings` when an AI step ran or failed. |

## Example response

```json
{
  "request": {
    "endpoint": "place",
    "engine": "google",
    "place_id": "ChIJ94DTm1cDdkgRibmgxzXy2EQ",
    "country": "gb",
    "language": "en"
  },
  "results": [
    {
      "title": "Monmouth Coffee Company",
      "address": "2 Park St, London SE1 9AB",
      "country": "GB",
      "latitude": 51.5055334,
      "longitude": -0.0914069,
      "timezone": "Europe/London",
      "rating": 4.5,
      "rating_count": 3039,
      "type": "Coffee shop",
      "types": [
        "Coffee shop",
        "Cafe"
      ],
      "website": "http://www.monmouthcoffee.co.uk/",
      "phone_number": "020 7232 3010",
      "international_phone_number": "+44 20 7232 3010",
      "description": "Fair-trade coffee & gourmet treats in the cafe & whole or freshly ground beans bagged to take home.",
      "opening_hours": {
        "Monday": "7:30 am–6 pm",
        "Sunday": "Closed"
      },
      "weekly_hours": {
        "monday": [
          {
            "open": "07:30",
            "close": "18:00"
          }
        ],
        "sunday": []
      },
      "photos": [
        {
          "url": "https://lh3.googleusercontent.com/…=w741-h472-k-no",
          "width": 741,
          "height": 472,
          "source": "business"
        }
      ],
      "google_maps_url": "https://maps.google.com/?cid=4960981302344989065",
      "place_id": "ChIJ94DTm1cDdkgRibmgxzXy2EQ",
      "cid": "4960981302344989065",
      "fid": "0x487603579bd380f7:0x44d8f235c7a0b989"
    }
  ],
  "meta": {
    "request_id": "req_01J8ZK4M6Q2V7",
    "credits_used": 1,
    "cached": false,
    "engine": "google",
    "latency_ms": 1034,
    "parse_quality": "ok",
    "resolved_urls": true
  }
}
```

## Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `invalid_request` | A parameter is missing or invalid. |
| 401 | `unauthorized` | The API key is missing, invalid or revoked. |
| 402 | `insufficient_credits` | Your balance is too low. Buy a pack or wait for the monthly free grant. |
| 429 | `rate_limited` | Too many requests per second for your plan. Retry after the Retry-After header. |
| 503 | `upstream_error` | Google could not be fetched or parsed. Not billed; retry after Retry-After. |

All errors: https://serpkite.com/docs/errors

## Notes

- Addresses, categories, hours text and descriptions follow `language`: with `language: "ru"` a Moscow café has `type: "Ресторан"` and `opening_hours` like `{"Monday": "24 часа в сутки"}`. `weekly_hours`, `country` and `timezone` are the same in every language.
- Use `max_age` to re-check a listing (hours, phone, website) at half price from the cache.

## Related

- [Maps](https://serpkite.com/docs/endpoints/maps)
- [Reviews](https://serpkite.com/docs/endpoints/reviews)
- [Localization](https://serpkite.com/docs/localization)