> ## Documentation Index
> Fetch the complete documentation index at: https://docs.graphext.com/llms.txt
> Use this file to discover all available pages before exploring further.

# fetch_google_places

> Fetch information about the most relevant places surrounding a location. 

Given the latitude and longitude coordinates of a location in each row, uses the *Google Places* API to enrich the
dataset with information about the surrounding businesses, their ratings etc. See below for further information about
the specific columns to be added by the step.

???+ info "API integration"
To use this step your team needs to have the *Google Places* integration configured in Graphext. The corresponding credentials
are required to connect to a third-party API. You can configure API integrations following the `INTEGRATIONS` or `ADD INTEGRATION`
link in the top-left corner of your Team's page, selecting `API keys`, and then the name of the desired third-party service.

To enable the *Google Places* integration in particular you will need access to Google's Places API. Follow the instructions
[here](https://developers.google.com/places/web-service/get-api-key) to create the required API key.

## Usage

The following example shows how the step can be used in a recipe.

<Accordion title="Examples" icon="code" defaultOpen="true">
  <Tabs>
    <Tab title="Example 1">
      To search places within a default radius of 1.5km and of arbitrary type

      ```stan theme={null}
      fetch_google_places(ds.lat, ds.lon) -> (
        ds.places_total,
        ds.places_number_ratings,
        ds.places_ratings_mean,
        ds.places_number_types,
        ds.places_types,
        ds.places_names
      )
      ```
    </Tab>

    <Tab title="Signature">
      General syntax for using the step in a recipe. Shows the inputs and outputs the step is expected to receive and will produce respectively. For futher details see sections below.

      ```stan theme={null}
      fetch_google_places(lat: number, lon: number, {
          "param": value,
          ...
      }) -> (
      	places_total: number,
      	places_number_ratings: number,
      	places_ratings_mean: number,
      	places_number_types: number,
      	places_types: list[category],
      	places_names: list[category]
      )
      ```
    </Tab>
  </Tabs>
</Accordion>

## Inputs & Outputs

The following are the inputs expected by the step and the outputs it produces. These are generally
columns (`ds.first_name`), datasets (`ds` or `ds[["first_name", "last_name"]]`) or models (referenced
by name e.g. `"churn-clf"`).

<Accordion title="Inputs" icon="right-to-bracket">
  <ParamField path="lat" type="column[number]" required>
    Column containing the latitude of each location.
  </ParamField>

  <ParamField path="lon" type="column[number]" required>
    Column containing the longitude of each location.
  </ParamField>
</Accordion>

<Accordion title="Outputs" icon="right-from-bracket">
  <ParamField path="places_total" type="column[number]" required>
    Number of places the API returned, maximum 10.
  </ParamField>

  <ParamField path="places_number_ratings" type="column[number]" required>
    Number of ratings on average for the places found, proxy for place popularity.
  </ParamField>

  <ParamField path="places_ratings_mean" type="column[number]" required>
    Average of the ratings of the places found, proxy for location index.
  </ParamField>

  <ParamField path="places_number_types" type="column[number]" required>
    Number of different types of places found.
  </ParamField>

  <ParamField path="places_types" type="column[list[category]]" required>
    Types of the places found, for possible categories see [here](https://developers.google.com/places/web-service/supported_types).
  </ParamField>

  <ParamField path="places_names" type="column[list[category]]" required>
    Names of the places found.
  </ParamField>
</Accordion>

## Configuration

The following parameters can be used to configure the behaviour of the step by including them in
a json object as the last "input" to the step, i.e. `step(..., {"param": "value", ...}) -> (output)`.

<Accordion title="Parameters" defaultOpen="true" icon="sliders">
  <ParamField path="integration" type="string" required>
    ID of the integration you'd like to use.
  </ParamField>

  <ParamField path="radius" type="number" default="1500">
    Search radius in meters around the given location.

    Values must be in the following range:

    ```javascript theme={null}
    10 ≤ radius < inf
    ```
  </ParamField>

  <ParamField path="type" type="[string, null]">
    Search for a specific type of place only.
    For supported types also see the [Google Places documentation here](https://developers.google.com/places/web-service/supported_types).

    Values must be one of the following:

    `accounting` `airport` `amusement_park` `aquarium` `art_gallery` `atm` `bakery` `bank` `bar` `beauty_salon` `bicycle_store` `book_store` `bowling_alley` `bus_station` `cafe` `campground` `car_dealer` `car_rental` `car_repair` `car_wash` `casino` `cemetery` `church` `city_hall` `clothing_store` `convenience_store` `courthouse` `dentist` `department_store` `doctor` `drugstore` `electrician` `electronics_store` `embassy` `fire_station` `florist` `funeral_home` `furniture_store` `gas_station` `grocery_or_supermarket` `gym` `hair_care` `hardware_store` `hindu_temple` `home_goods_store` `hospital` `insurance_agency` `jewelry_store` `laundry` `lawyer` `library` `light_rail_station` `liquor_store` `local_government_office` `locksmith` `lodging` `meal_delivery` `meal_takeaway` `mosque` `movie_rental` `movie_theater` `moving_company` `museum` `night_club` `painter` `park` `parking` `pet_store` `pharmacy` `physiotherapist` `plumber` `police` `post_office` `primary_school` `real_estate_agency` `restaurant` `roofing_contractor` `rv_park` `school` `secondary_school` `shoe_store` `shopping_mall` `spa` `stadium` `storage` `store` `subway_station` `supermarket` `synagogue` `taxi_stand` `tourist_attraction` `train_station` `transit_station` `travel_agency` `university` `veterinary_care` `zoo`
  </ParamField>

  <ParamField path="keyword" type="string" default="">
    Specific keyword to use in the search for places.

    <Accordion title="Examples">
      * burger
    </Accordion>
  </ParamField>
</Accordion>