--- title: "Places" description: "在 Google 地图 上查找地点。" --- > Every apinoa docs page as markdown: https://apinoa.com/llms.txt (all in one file: https://apinoa.com/llms-full.txt; this API family in one file: https://apinoa.com/docs/serp/llms.txt) ```http GET | POST /v1/google/places ``` 参数可以用 `GET` 的查询字符串发送，也可以用 `POST` 的 JSON 请求体发送，两者等价。 ## 请求 ```bash tab="cURL" curl "https://gateway.apinoa.com/v1/google/places?q=coffee&near=Austin,+TX&country=US&limit=5" \ -H "x-api-key: $APINOA_API_KEY" ``` ```js tab="JavaScript" const params = new URLSearchParams({ q: "coffee", near: "Austin, TX", country: "US", limit: "5" }); const res = await fetch(`https://gateway.apinoa.com/v1/google/places?${params}`, { headers: { "x-api-key": process.env.APINOA_API_KEY }, }); const { success, data, error } = await res.json(); ``` ```python tab="Python" import os import requests res = requests.get( "https://gateway.apinoa.com/v1/google/places", params={"q": "coffee", "near": "Austin, TX", "country": "US", "limit": "5"}, headers={"x-api-key": os.environ["APINOA_API_KEY"]}, ) body = res.json() ``` ## 参数 | Parameter | Type | Required | Notes | |---|---|---|---| | `country` | enum | | The market, as an ISO 3166 country code. `US` `GB` `CA` `AU` `DE` `FR` `IT` `AT` `JP` `KR` | | `cursor` | string | | The previous page's `cursor`. Pass it alone for the next page. | | `lang` | string | | Interface language. | | `limit` | integer 1–60 | | Results wanted (default 20, at most 60). More than one page is charged per page. | | `location` | string | | Search as if from this point: `lat,lng`. | | `near` | string | | Search around this place name, or a `lat,lng` point. | | `q` | string | | The query, search operators included. | The same parameters, and every response type, are in the OpenAPI document: https://apinoa.com/openapi.json ## 响应 在 `data` 中返回 [`PlacesPage`](/docs/api-reference/serp/response-schema#placespage)。 真实响应的节选：数组只保留前几项，长文本已截断。 ```json { "success": true, "data": { "engine": "google", "query": "coffee", "outcome": "results", "type": "maps", "near": "Austin, TX", "country": "US", "lang": "en", "places": [ { "id": "0x8644ca6bc309e81b:0x1f1a903bbb66839", "name": "Epoch Coffee", "url": "https://www.google.com/maps/place/data=!4m2!3m1!1s0x8644ca6bc309e81b:0x1f1a903bbb66839", "address": { "full": "221 W N Loop Blvd, Austin, TX 78751", "street": "221 W N Loop Blvd", "city": "Austin", "region": "TX", "postalCode": "78751", "country": "US" }, "coordinates": {"lat": 30.318603699999997, "lng": -97.72454019999999}, "categories": ["Coffee shop"], "rating": 4.5, "reviewCount": 2534, "phone": "(512) 454-3762", "website": "http://www.epochcoffee.com/", "hours": [{"day": "Thursday", "hours": "Open 24 hours"}, {"day": "Friday", "hours": "Open 24 hours"}], "photos": [ "https://lh3.googleusercontent.com/grass-cs/AABkmLfAFGuJt7CdI-CWuV7SnfjNA86KhQMnioybPp9RFelnIsLJKhY30zSOUupXC0AsbQN8dJC6Z5Qoju7i9WXbkITWwEEw1E-et0lccw9ovMNFTQ7E8…", "https://lh3.googleusercontent.com/grass-cs/AABkmLfAFGuJt7CdI-CWuV7SnfjNA86KhQMnioybPp9RFelnIsLJKhY30zSOUupXC0AsbQN8dJC6Z5Qoju7i9WXbkITWwEEw1E-et0lccw9ovMNFTQ7E8…" ], "attributes": [ {"group": "Accessibility", "label": "Wheelchair accessible entrance"}, {"group": "Accessibility", "label": "Wheelchair accessible parking lot"} ], "status": "open", "description": "Cool, vibrant small-chain cafe featuring nibbles, tea & carefully brewed espresso drinks.", "ext": { "placeId": "ChIJG-gJw2vKRIYROWi2uwOp8QE", "kgmid": "/g/1v76_180", "timeZone": "America/Chicago", "summary": "Hip coffee shop with light bites", "areas": ["Americas"], "owner": { "name": "Epoch Coffee (Owner)", "image": "https://lh5.googleusercontent.com/-WzsTjK0vgDQ/AAAAAAAAAAI/AAAAAAAAAAA/uanMPnqDLak/s44-p-k-no-ns-nd/photo.jpg" } }, "photoCount": 838, "statusText": "Open 24 hours", "neighborhood": "North Loop", "reviewsUrl": "https://search.google.com/local/reviews?placeid=ChIJG-gJw2vKRIYROWi2uwOp8QE&q=coffee+near+Austin,+TX&hl=en&gl=US" }, { "id": "0x8644b5554461664d:0xbc4ff333ec9ad1ad", "name": "Mozart's Coffee Roasters", "url": "https://www.google.com/maps/place/data=!4m2!3m1!1s0x8644b5554461664d:0xbc4ff333ec9ad1ad", "address": { "full": "3825 Lake Austin Blvd, Austin, TX 78703", "street": "3825 Lake Austin Blvd", "city": "Austin", "region": "TX", "postalCode": "78703", "country": "US" }, "coordinates": {"lat": 30.295469599999997, "lng": -97.78395119999999}, "categories": ["Coffee shop", "Bakery"], "rating": 4.5, "reviewCount": 10987, "phone": "(512) 477-2900", "website": "https://mozartscoffee.com/", "hours": [{"day": "Thursday", "hours": "7 AM–12 AM"}, {"day": "Friday", "hours": "7 AM–12 AM"}], "photos": [ "https://lh3.googleusercontent.com/grass-cs/AABkmLf_c6cXdmPiP9ZYH3st9N7FqJbZI4VuqzeQCF5LcTx3ZJ2ByPLryWaZ8lCIIa1MlanBvALs0JRSUE10dd3mcUDaE36C2-rSGXiH-i8Wyhsd9YNQA…", "https://lh3.googleusercontent.com/grass-cs/AABkmLf_c6cXdmPiP9ZYH3st9N7FqJbZI4VuqzeQCF5LcTx3ZJ2ByPLryWaZ8lCIIa1MlanBvALs0JRSUE10dd3mcUDaE36C2-rSGXiH-i8Wyhsd9YNQA…" ], "attributes": [ {"group": "Accessibility", "label": "Wheelchair accessible entrance"}, {"group": "Accessibility", "label": "Wheelchair accessible parking lot"} ], "status": "open", "description": "Beans flame-roasted on-site, plus bakery goods, frequent live music & patio seating on Lake Austin.", "ext": { "placeId": "ChIJTWZhRFW1RIYRrdGa7DPzT7w", "kgmid": "/m/020z4hc", "timeZone": "America/Chicago", "summary": "Lakeside coffee & desserts", "areas": ["Americas"], "owner": { "name": "Mozart's Coffee Roasters (Owner)", "image": "https://lh3.googleusercontent.com/-88EjI7tZSV0/AAAAAAAAAAI/AAAAAAAAAAA/3-Wpwoe7iz0/s44-p-k-no-ns-nd/photo.jpg" } }, "photoCount": 17015, "statusText": "Open · Closes 12 AM", "neighborhood": "Westfield", "reviewsUrl": "https://search.google.com/local/reviews?placeid=ChIJTWZhRFW1RIYRrdGa7DPzT7w&q=coffee+near+Austin,+TX&hl=en&gl=US" } ], "page": {"index": 1, "size": 20}, "cursor": "SscpBRWdlu0MeCuvvWfumLp6ZHk-1P8xDBDrsmzZkWl5o3-lDXix1P_XUEvxpkqfyKI7tm1YhQWm7mOtUIJYrk4UBWGPY_uUHD2SxkjATHY3Ocs4DFVcnuMumeNNrTF0vXljq_zWiLqfV50YdIZM_TjGXr7uBsWh…", "fetchedAt": "2026-10-30T01:03:09.318Z" } } ``` ## 错误 | 状态 | 代码 | 含义 | |---|---|---| | 400 | `INVALID_CURSOR` | 该 `cursor` 不是本操作返回的。请不带它重新开始。 | | 400 | `INVALID_PARAMS` | 参数缺失、未知、超出范围，或该引擎不接受。消息中会指出是哪一个。 | | 401 | `UNAUTHORIZED` | 缺少 `x-api-key` 请求头，或密钥已吊销或未知。 | | 402 | `INSUFFICIENT_BALANCE` | 余额不足以支付本次调用。请在控制台充值。 | | 429 | `MARKETPLACE_SATURATED` | 并发调用过多。请等待 `Retry-After` 秒后重试。 | | 502 | `UPSTREAM_ERROR` | 引擎返回了无法使用的内容。请退避后重试。 | | 503 | `SERVICE_UNAVAILABLE` | 临时故障。请退避后重试。 | 全部错误代码见 [Errors](/docs/errors)。失败的调用不计费。 ## 价格 **Price** $0.0012 per call, plus $0.0012 for each extra call it makes — at most 2 more, so $0.0036 in total. [List price](https://apinoa.com/en/pricing); the rate steps down above 1,000 calls a day. ## 说明 - 用 `near` 在地名附近搜索，或用 `location`（`lat,lng`）在坐标附近搜索。 - `limit` 超过一页时会继续读取后续页面，每页 1 个单位。