---
title: "Quote a collection"
method: POST
path: "/collections/quote"
tags: ["Collections"]
---

# Quote a collection

`POST /collections/quote`

## Request

- Base URL: `https://api.gmaps.dev/v1`
- URL: `https://api.gmaps.dev/v1/collections/quote`
- Auth: HTTP bearer

See what collecting an area would cost before you start it: how much of it we have searched recently, how many places we have saved there (those cost nothing), how many searches are left to run, and the most it can cost in credits. Needs an API key. Costs no credits and starts nothing.

## Request body

- object
  - `keywords` string[], required: What to search for, such as ["bakery", "coffee shop"]. One search per term.
  - `geo` union, required: Where to search. Give exactly one of: a Brazilian city as location, a lat/lng point with radiusM, a bbox, or a cityIbge with radiusKm.
    - object
      - `location` string, required
    - object
      - `lat` number, required
      - `lng` number, required
      - `radiusM` number, required
    - object
    - object
      - `cityIbge` integer, required
      - `radiusKm` number, required
  - `lang` string: The language to search in. New places come back in it. Two letters, such as pt or en.
  - `minRating` number, nullable: Keep only places rated at least this, from 1 to 5. Null keeps every place.
  - `maxPlaces` integer: Stop after this many places. Defaults to the most your plan collects at once.
  - `enrich` string[]: Add ["emails"] to also look for email addresses. Costs one more credit for each place that has one, and needs a paid plan.

## Response `200`

Quote a collection

- object
  - `data` object, required
    - `coverage` 'fresh' | 'partial' | 'new', required: `fresh`: we searched all of it recently. `new`: none of it. `partial`: some.
    - `squaresTotal` integer, required: How many searches the area takes: one per square of the area, for each term.
    - `squaresCovered` integer, required: How many of those we searched recently enough to reuse. Their places cost nothing.
    - `squaresToSearch` integer, required: How many searches a collection would still have to run. Each takes a few minutes.
    - `placesKnown` integer, required: Places we have saved in this area. They cost nothing.
    - `maxCost` integer, required: The most this can cost, in credits. It costs less when the new squares hold fewer places.
    - `sample` object[], required: A few of the places we already have, so you can see what is there.
      - `id` string, uuid, required: Our id for the place. It never changes, and get_place takes it. Google's own id is `identity.cid`.
      - `identity` object, required: Who the place is: its name, category and ids.
        - `cid` string, nullable, required: Google's id for the place: up to 25 digits, always as a string. It does not fit in a JavaScript number, so reading it as one loses the last digits. Null when Maps didn't give one.
        - `placeId` string, nullable, required: Google's place ID. Null when Maps didn't give one.
        - `dataId` string, nullable, required: Google Maps' own id for the listing: two hexadecimal numbers joined by a colon. Null when Maps didn't give one.
        - `name` string, required: The business's name, as Maps shows it.
        - `category` string, nullable, required: The kind of business, in the language of the last search that collected it: "Bakery", "Padaria".
        - `mapsUrl` string, uri, required: The place's page on Google Maps.
        - `description` string, nullable, required: What the business wrote about itself on Maps. Null when it wrote nothing.
        - `status` string, nullable, required: What its Maps listing said when we collected it (`meta.scrapedAt`), such as "Permanently closed".
      - `contact` object, required: How to reach the business.
        - `phones` string[], required: Phone numbers, as Maps shows them. Empty when it lists none.
        - `website` string, uri, nullable, required: The business's own website. Null when Maps lists none.
        - `emails` string[]: Email addresses we found for the place. Sent only on a plan with emails, after you accept the acceptable use policy, and only when we have at least one. So if you have access and `emails` is missing, we have none.
      - `location` object, required: Where the place is.
        - `address` string, nullable, required: The whole address on one line, as Maps writes it.
        - `completeAddress` object, nullable, required: The same address in parts. Null when Maps didn't split it.
          - `borough` string, nullable, required: The neighborhood: the bairro, in Brazil.
          - `street` string, nullable, required
          - `city` string, nullable, required
          - `postalCode` string, nullable, required: The postal code: the CEP, in Brazil.
          - `state` string, nullable, required
          - `country` string, nullable, required
        - `city` string, nullable, required: The city, taken from `completeAddress`.
        - `state` string, nullable, required: The state, taken from `completeAddress`.
        - `country` string, nullable, required: The country, taken from `completeAddress`.
        - `lat` number, nullable, required: Latitude in degrees. Null when we have no coordinates, and then `lng` is null too.
        - `lng` number, nullable, required: Longitude in degrees. Null exactly when `lat` is.
        - `plusCode` string, nullable, required: Google's Plus Code for the spot, a short code that works like an address.
      - `ratings` object, required: The star rating and its reviews.
        - `rating` number, nullable, required: The average star rating, 0 to 5. Null when nobody has rated it.
        - `reviewCount` integer, nullable, required: How many reviews it has. Null when Maps didn't say.
        - `reviewsPerRating` object, nullable, required: How many reviews gave each star count. Stars Google left out are missing here too.
      - `hours` object, required: When it opens and how busy it gets.
        - `timezone` string, nullable, required: The place's time zone, such as America/Sao_Paulo.
        - `openHours` object, nullable, required: Day name to the hours it is open, both in the language of the last search that collected the place. Null when Maps shows no hours.
        - `popularTimes` object, nullable, required: Day name to hour ("0" to "23") to how busy it usually is, from 0 to 100. Null when Maps shows none.
      - `commerce` object, required: Prices, amenities, payments, and links to order or book.
        - `priceRange` string, nullable, required: The price band Maps shows, such as "$$". Null when it shows none.
        - `about` object[], required: What the place says about itself on Maps, in groups such as accessibility or payments.
          - `id` string, required
          - `name` string, required
          - `options` object[], required: What Maps lists in this group, such as a wheelchair-accessible entrance.
            - `name` string, required
            - `enabled` boolean, required: True when the place has it, false when Maps says it doesn't.
            - `values` string[]
        - `creditCardsAccepted` string[], required: The cards it takes, as Maps lists them. Empty when Maps doesn't say.
        - `menu` object, nullable, required: A link to its menu. Null when it has none.
          - `link` string, uri, required: The link to open.
          - `source` string, required: Who offers it: "Google", the business's own site, a delivery app.
        - `orderOnline` object[], required: Where to order from it online. Empty when Maps lists none.
          - `link` string, uri, required: The link to open.
          - `source` string, required: Who offers it: "Google", the business's own site, a delivery app.
        - `reservations` object[], required: Where to book with it. Empty when Maps lists none.
          - `link` string, uri, required: The link to open.
          - `source` string, required: Who offers it: "Google", the business's own site, a delivery app.
      - `meta` object, required: When we collected the place, and whether it cost you a credit.
        - `scrapedAt` string, date-time, required: When we last collected this place.
        - `firstSeenAt` string, date-time, required: When we first collected this place.
        - `cached` boolean, required: True when this came from what we already had, which costs nothing.
  - `meta` union
    - object
      - `total` integer, required: Every item that matches, not just this page.
      - `limit` integer, required: The most items a page holds.
      - `offset` integer, required: How many items came before this page.
      - `hasMore` boolean, required: True when another page follows.
    - object
      - `cost` integer, required: Credits this call took.
      - `creditsRemaining` integer, required: Credits left after this call, this month's and bought ones together.
      - `requestId` string, required: This call's id. Send it to support if something went wrong.
      - `cached` boolean: True when this response used only saved results.

## Other responses

- `default`: Any other failure.

---

[API](https://skmtc.dev/gmaps/apis/gmaps-dev.md) · [All operations](https://skmtc.dev/gmaps/apis/gmaps-dev/llms.txt) · [OpenAPI document](https://skmtc.dev/gmaps/apis/gmaps-dev/revisions/0b3459aaf802?raw)