google_maps_place

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/scrapefield-com/json-schema/scrapefield-com-google-maps-place-schema.json",
  "title": "google_maps_place",
  "description": "One business or place, as its Google Maps listing shows it.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/scrapefield-com-openapi.json#/components/schemas/google_maps_place",
  "type": "object",
  "required": [
    "place_id",
    "name",
    "category",
    "categories",
    "formatted_address",
    "address",
    "location",
    "plus_code",
    "rating",
    "user_ratings_total",
    "rating_distribution",
    "price_level",
    "formatted_phone_number",
    "international_phone_number",
    "website",
    "url",
    "business_status",
    "opening_hours",
    "popular_times",
    "about",
    "claimed",
    "photo"
  ],
  "properties": {
    "place_id": {
      "type": "string",
      "description": "Google's place ID — the same one the Places API and every Maps URL use."
    },
    "name": {
      "type": "string",
      "description": "As the listing shows it."
    },
    "category": {
      "type": [
        "string",
        "null"
      ],
      "description": "The category printed under the name, e.g. \"Coffee shop\"."
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "One category."
      },
      "description": "Every category on the listing, the main one first."
    },
    "formatted_address": {
      "type": [
        "string",
        "null"
      ],
      "description": "The address as one line, as Google formats it."
    },
    "address": {
      "type": "object",
      "required": [
        "street",
        "city",
        "region",
        "postal_code",
        "country_code"
      ],
      "properties": {
        "street": {
          "type": [
            "string",
            "null"
          ],
          "description": "Street and number. `null` where the source gives the address as one line: see `formatted_address`."
        },
        "city": {
          "type": [
            "string",
            "null"
          ],
          "description": "City or town."
        },
        "region": {
          "type": [
            "string",
            "null"
          ],
          "description": "State, province or region."
        },
        "postal_code": {
          "type": [
            "string",
            "null"
          ],
          "description": "Postal or ZIP code."
        },
        "country_code": {
          "type": [
            "string",
            "null"
          ],
          "description": "ISO 3166-1 alpha-2, e.g. `US`."
        }
      },
      "additionalProperties": false,
      "description": "The same address in parts. Where the source gives the address as one line, only `country_code` is filled."
    },
    "location": {
      "type": [
        "object",
        "null"
      ],
      "required": [
        "lat",
        "lng"
      ],
      "properties": {
        "lat": {
          "type": "number",
          "description": "Latitude."
        },
        "lng": {
          "type": "number",
          "description": "Longitude."
        }
      },
      "additionalProperties": false,
      "description": "The pin. `null` when the source does not give it."
    },
    "plus_code": {
      "type": [
        "string",
        "null"
      ],
      "description": "The global plus code, e.g. `87G8P2QX+RV`."
    },
    "rating": {
      "type": [
        "number",
        "null"
      ],
      "description": "The star rating, 1.0–5.0. `null` until the place has ratings."
    },
    "user_ratings_total": {
      "type": [
        "integer",
        "null"
      ],
      "description": "How many ratings the star rating is the average of."
    },
    "rating_distribution": {
      "type": [
        "object",
        "null"
      ],
      "required": [
        "1",
        "2",
        "3",
        "4",
        "5"
      ],
      "properties": {
        "1": {
          "type": "integer",
          "description": "One-star ratings."
        },
        "2": {
          "type": "integer",
          "description": "Two-star ratings."
        },
        "3": {
          "type": "integer",
          "description": "Three-star ratings."
        },
        "4": {
          "type": "integer",
          "description": "Four-star ratings."
        },
        "5": {
          "type": "integer",
          "description": "Five-star ratings."
        }
      },
      "additionalProperties": false,
      "description": "How many ratings of each star value, as the listing's bar chart shows them."
    },
    "price_level": {
      "type": [
        "integer",
        "null"
      ],
      "description": "0 (free) to 4 (very expensive), as the Places API counts it."
    },
    "formatted_phone_number": {
      "type": [
        "string",
        "null"
      ],
      "description": "The phone number in local format."
    },
    "international_phone_number": {
      "type": [
        "string",
        "null"
      ],
      "description": "With the country code, e.g. `+1 718-555-0142`."
    },
    "website": {
      "type": [
        "string",
        "null"
      ],
      "format": "uri",
      "description": "The business's own site."
    },
    "url": {
      "type": "string",
      "format": "uri",
      "description": "The place on Google Maps."
    },
    "business_status": {
      "type": "string",
      "enum": [
        "OPERATIONAL",
        "CLOSED_TEMPORARILY",
        "CLOSED_PERMANENTLY"
      ],
      "description": "As the Places API reports it."
    },
    "opening_hours": {
      "type": [
        "object",
        "null"
      ],
      "required": [
        "weekday_text",
        "periods"
      ],
      "properties": {
        "weekday_text": {
          "type": "array",
          "items": {
            "type": "string",
            "description": "One day, e.g. \"Monday: 8:30 AM – 5:30 PM\" or \"Sunday: Closed\"."
          },
          "description": "Seven lines, Monday first, as the listing prints them."
        },
        "periods": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "open",
              "close"
            ],
            "properties": {
              "open": {
                "type": "object",
                "required": [
                  "day",
                  "time"
                ],
                "properties": {
                  "day": {
                    "type": "integer",
                    "description": "0 is Sunday."
                  },
                  "time": {
                    "type": "string",
                    "description": "24-hour `HHMM`, local time."
                  }
                },
                "additionalProperties": false,
                "description": "When it opens."
              },
              "close": {
                "type": [
                  "object",
                  "null"
                ],
                "required": [
                  "day",
                  "time"
                ],
                "properties": {
                  "day": {
                    "type": "integer",
                    "description": "0 is Sunday."
                  },
                  "time": {
                    "type": "string",
                    "description": "24-hour `HHMM`, local time."
                  }
                },
                "additionalProperties": false,
                "description": "When it closes."
              }
            },
            "additionalProperties": false
          },
          "description": "The same hours as data. A place open around the clock has one period with no `close`."
        }
      },
      "additionalProperties": false,
      "description": "Regular opening hours. `null` when the listing has none."
    },
    "popular_times": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "object",
        "required": [
          "day",
          "busyness"
        ],
        "properties": {
          "day": {
            "type": "integer",
            "description": "0 is Sunday."
          },
          "busyness": {
            "type": "array",
            "items": {
              "type": "integer",
              "description": "One hour, 0–100."
            },
            "description": "Twenty-four values, midnight first, 0–100 relative to the place's busiest hour."
          }
        },
        "additionalProperties": false
      },
      "description": "The \"Popular times\" chart. `null` for places too quiet to have one."
    },
    "about": {
      "type": "object",
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string",
          "description": "One item, e.g. \"Takeout\"."
        },
        "description": "The items under one heading, as the listing prints them."
      },
      "description": "The listing's About tab, by heading: `service_options`, `accessibility`, `amenities`, `payments` and so on — only the headings the place has."
    },
    "claimed": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Whether the owner has claimed the listing. Unclaimed ones offer \"Own this business?\"."
    },
    "photo": {
      "type": [
        "object",
        "null"
      ],
      "required": [
        "url",
        "width",
        "height",
        "author_name",
        "author_url"
      ],
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "The image on Google's CDN. We do not rehost images."
        },
        "width": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Pixels."
        },
        "height": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Pixels."
        },
        "author_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Who uploaded it, as the listing credits them. `null` for the owner's own photos."
        },
        "author_url": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri",
          "description": "Their Google Maps contributor page."
        }
      },
      "additionalProperties": false,
      "description": "The listing's main photo."
    }
  },
  "additionalProperties": false
}