> ## 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_location

> Extract formatted address, locality, area, state, country and geographical coordinates from one or more address columns. 

It is possible to specify a postal code as a standalone column, but this will be interpreted as American
without a proper prefix. To use Spanish postal codes indicate this using the "CP" prefix, e.g. "CP 28001".

To use this step your team needs to have the *Google Location* 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 Location* integration in particular you will need access to Google's geocoding service. Follow the instructions
[here](https://developers.google.com/maps/documentation/geocoding/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">
      Since the step has no configuration parameters, simply use

      ```stan theme={null}
      fetch_location(ds.address) -> (
        ds.canonical_address,
        ds.locality,
        ds.area,
        ds.state,
        ds.country,
        ds.lat,
        ds.lon)
      ```
    </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_location(*address_columns: text|category|number, {
          "param": value,
          ...
      }) -> (
      	formatted_address: category,
      	locality: category,
      	area: category,
      	state: category,
      	country: category,
      	lat: number,
      	lon: number
      )
      ```
    </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="*address_columns" type="column[text|category|number]">
    One or more text or categorical columns containing all or parts of an address (e.g. street, city, postal code etc.).
    If several parts are specified in a single column they should be separated by a comma.
  </ParamField>
</Accordion>

<Accordion title="Outputs" icon="right-from-bracket">
  <ParamField path="formatted_address" type="column[category]" required>
    Categorical column containing the original address in a standardized format.
  </ParamField>

  <ParamField path="locality" type="column[category]" required>
    Categorical column containing each address's locality.
  </ParamField>

  <ParamField path="area" type="column[category]" required>
    Categorical column containing each address's area.
  </ParamField>

  <ParamField path="state" type="column[category]" required>
    Categorical column containing each address's state or region.
  </ParamField>

  <ParamField path="country" type="column[category]" required>
    Categorical column containing each address's country.
  </ParamField>

  <ParamField path="lat" type="column[number]" required>
    Numeric column containing the latitude coordinate of the address.
  </ParamField>

  <ParamField path="lon" type="column[number]" required>
    Numeric column containing the longitude coordinate of the address.
  </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>
</Accordion>