10.0: Geocode locations in natural language with interaction automations and Geoapify

[jstanden]

Introduction

Let's assume we need to convert user-provided natural language locations (e.g. street addresses, landmarks) into geolocation coordinates (latitude/longitude) for visualizing on a map.

This process is called "geocoding".

In this example, we'll build a geocoding service in Cerb 10 that you can reuse in any workflow.

Sign up for the Geoapify API

Geocoding requires a large dataset of map locations. It doesn't make sense for us to ship this with Cerb. Instead, we're going to integrate with an API from Geoapify.

If you don't already have a Geoapify account, you can start with a free one here: https://www.geoapify.com/pricing

This same approach will work with any geocoding API: Google Maps, OpenWeatherMap, Geocodeapi, etc.

Import the example package in Cerb

Navigate to Setup >> Packages >> Import and paste the following package:

{
  "package": {
    "name": "Geoapify for Cerb",
    "requires": {
      "cerb_version": "10.0.0"
    },
    "configure": {
      "placeholders": [],
      "prompts": [
        {
          "type": "text",
          "label": "API Key",
          "key": "prompt_api_key",
          "params": {
            "default": "",
            "placeholder": "(paste your Geoapify API Key)"
          }
        }
      ]
    }
  },
  "records": [
    {
      "uid": "service_geoapify",
      "_context": "connected_service",
      "name": "Geoapify for Cerb",
      "extension_id": "cerb.service.provider.api_key",
      "params": {
        "api_base_url": "https://api.geoapify.com/",
        "api_key_name": "apiKey",
        "api_key_location": "url"
      }
    },
    {
      "uid": "account_geoapify",
      "_context": "connected_account",
      "name": "Geoapify",
      "service_id": "{{{uid.service_geoapify}}}",
      "uri": "geoapify",
      "owner__context": "app",
      "owner_id": 0,
      "params": {
        "api_key": "{{{prompt_api_key}}}"
      }
    },
    {
      "uid": "automation_geoapify_geocode",
      "_context": "automation",
      "name": "wgm.services.geoapify.geocode",
      "extension_id": "cerb.trigger.automation.function",
      "description": "Return GeoJSON features for a given location",
      "script": "inputs:\n  text/location:\n    type: freeform\n    required@bool: yes\n\nstart:\n  http.request/geocode:\n    output: http_response\n    inputs:\n      method: GET\n      url: https://api.geoapify.com/v1/geocode/search?text={{inputs.location|url_encode}}\n      headers@text:\n        User-Agent: Cerb 10.0\n      authentication: cerb:connected_account:geoapify\n    on_success:\n      return:\n        geojson@json: {{http_response.body}}\n",
      "policy_kata": "commands:\n  http.request:\n    deny/url@bool: {{inputs.url is not prefixed ('https://api.geoapify.com/v1/geocode/search?')}}\n    allow@bool: yes"
    },
    {
      "uid": "automation_geoapify_interaction",
      "_context": "automation",
      "name": "wgm.example.geoapify.location",
      "extension_id": "cerb.trigger.interaction.worker",
      "description": "Interaction to convert a text location to geo coordinates",
      "script": "start:\n  await/location:\n    form:\n      title: Location Lookup\n      elements:\n        text/prompt_location:\n          label: Location\n          required@bool: yes\n          placeholder: (e.g. 123 Main, Anywhere, USA)\n  \n  function/lookup:\n    uri: cerb:automation:wgm.services.geoapify.geocode\n    output: results\n    inputs:\n      location@key: prompt_location\n    on_success:\n      set:\n        features@key: results:geojson:features\n  \n  await/select:\n    form:\n      title: Select Location\n      elements:\n        sheet/prompt_result:\n          label: Choose a location:\n          required@bool: yes\n          data@key: features\n          limit: 10\n          schema:\n            layout:\n              headings@bool: no\n              paging@bool: no\n            columns:\n              selection/key:\n                params:\n                  mode: single\n                  value_template@raw: {{__row.index}}\n              text/name:\n                params:\n                  bold@bool: yes\n                  value_template@raw: {{properties.formatted}}\n              text/coordinates:\n                params:\n                  value_template@raw: {{properties.lat}}, {{properties.lon}}\n  \n  set:\n    feature@key: features:{{prompt_result}}:properties\n  \n  await/results:\n    form:\n      title: Coordinates\n      elements:\n        say:\n          content@text:\n            #### {{feature.formatted}}\n            **Latitude/Longitude:** {{feature.lat}}, {{feature.lon}}\n        map:\n          resource:\n            uri: cerb:resource:map.world.countries\n          projection:\n            type: mercator\n            scale: 90\n            center:\n              latitude: {{feature.lat}}\n              longitude: {{feature.lon}}\n            zoom:\n              latitude: {{feature.lat}}\n              longitude: {{feature.lon}}\n              scale: 3.5\n          points:\n            data:\n              point:\n                latitude: {{feature.lat}}\n                longitude: {{feature.lon}}\n                properties@key: feature\n            size:\n              default: 5\n            fill:\n              default: #FF0000\n  \n  return:\n    coordinates:\n      label: {{feature.formatted}}\n      lat: {{feature.lat}}\n      lon: {{feature.lon}}\n",
      "policy_kata": "commands:\n  function:\n    deny/name@bool: {{uri != 'wgm.services.geoapify.geocode'}}\n    allow@bool: yes"
    }
  ],
  "toolbars": [
    {
      "toolbar": "global.menu",
      "kata": "interaction/geocode:\n  label: Geocode Location\n  uri: cerb:automation:wgm.example.geoapify.location\n  icon: globe\n"
    }
  ]
}

Click the Import button.

Paste your Geoapify API key from above.

Click the Import button again.

Geocoding

Reload the page and click on the floating, circular Cerb icon in the lower right.

The menu has a new Geocode Location interaction.

Click that and an interaction will start. You can enter a street address, city, country, or landmark to find its coordinates.

cerb10_interaction_geocode.mov

This example simply displays the location on a map. You could modify it to meet your needs: insert coordinates into an email draft, set a custom field, find store locations in proximity to the coordinates, and so on.

How it works

Connected service and account

The package imports and configures a connected service for Geoapify. It then creates a connected account for that service with the API key. That account is used by automations to interact with the API.

You'll find these in Search -> Connected Services and Search -> Connected Accounts.

Automations

The package imports two automations. You'll find these in Search -> Automations.

wgm.services.geoapify.geocode

This automation function "wraps" the geocoding API from Geoaplify. It takes a human readable location as input and sends that to the API through an HTTP request. It also uses the connected account above to securely append the API key to the request.

Any automation can run this function to turn a location into coordinates. The possible locations are returned as the geojson key.

inputs:
  text/location:
    type: freeform
    required@bool: yes

start:
  http.request/geocode:
    output: http_response
    inputs:
      method: GET
      url: https://api.geoapify.com/v1/geocode/search?text={{inputs.location|url_encode}}
      headers@text:
        User-Agent: Cerb 10.0
      authentication: cerb:connected_account:geoapify
    on_success:
      return:
        geojson@json: {{http_response.body}}

The policy allows the automation to use the http.request command for any URL beginning with https://api.geoapify.com/v1/geocode/search?.

commands:
  http.request:
    deny/url@bool: {{inputs.url is not prefixed ('https://api.geoapify.com/v1/geocode/search?')}}
    allow@bool: yes

wgm.example.geoapify.location

This interaction automation prompts a worker for a location (using continuations), uses the function above to generate a list of possible locations, prompts the user to choose one of those, then it displays the selected coordinates and plots them on a map.

The map prompt uses Maps KATA to draw the map. The automation generates that KATA on-the-fly.

Interactions can also return data to their "caller". In this example the global menu doesn't expect any results. For something like the email editor the interaction could return a snippet: to be inserted at the cursor.

start:
  await/location:
    form:
      title: Location Lookup
      elements:
        text/prompt_location:
          label: Location
          required@bool: yes
          placeholder: (e.g. 123 Main, Anywhere, USA)
  
  function/lookup:
    uri: cerb:automation:wgm.services.geoapify.geocode
    output: results
    inputs:
      location@key: prompt_location
    on_success:
      set:
        features@key: results:geojson:features
  
  await/select:
    form:
      title: Select Location
      elements:
        sheet/prompt_result:
          label: Choose a location:
          required@bool: yes
          data@key: features
          limit: 10
          schema:
            layout:
              headings@bool: no
              paging@bool: no
            columns:
              selection/key:
                params:
                  mode: single
                  value_template@raw: {{__row.index}}
              text/name:
                params:
                  bold@bool: yes
                  value_template@raw: {{properties.formatted}}
              text/coordinates:
                params:
                  value_template@raw: {{properties.lat}}, {{properties.lon}}
  
  set:
    feature@key: features:{{prompt_result}}:properties
  
  await/results:
    form:
      title: Coordinates
      elements:
        say:
          content@text:
            #### {{feature.formatted}}
            **Latitude/Longitude:** {{feature.lat}}, {{feature.lon}}
        map:
          resource:
            uri: cerb:resource:map.world.countries
          projection:
            type: mercator
            scale: 90
            center:
              latitude: {{feature.lat}}
              longitude: {{feature.lon}}
            zoom:
              latitude: {{feature.lat}}
              longitude: {{feature.lon}}
              scale: 3.5
          points:
            data:
              point:
                latitude: {{feature.lat}}
                longitude: {{feature.lon}}
                properties@key: feature
            size:
              default: 5
            fill:
              default: #FF0000
  
  return:
    coordinates:
      label: {{feature.formatted}}
      lat: {{feature.lat}}
      lon: {{feature.lon}}

The policy allows this automation to use the function: command with the wgm.services.geoapify.geocode automation above.

commands:
  function:
    deny/name@bool: {{uri != 'cerb:automation:wgm.services.geoapify.geocode'}}
    allow@bool: yes

Toolbar

The package modifies the global.menu toolbar to add the interaction. You'll find this in Search -> Toolbars.

You can add this interaction to other locations (e.g. organization cards) by adding it to other toolbars.

interaction/geocode:
  label: Geocode Location
  uri: cerb:automation:wgm.example.geoapify.location
  icon: globe