Skip to content

Appendix A: geocodeSearchService Field

This appendix provides a detailed description of the "geocodeSearchService" field, one of the fields used to define each of the Formbird components below:

1 Purpose

The "geocodeSearchService" field is an array of geocode service definitions. Currently the array can contain at most one geocode service definition.

  • A geocode service provides geocoding and reverse geocoding functionality.
  • Geocoding (AKA forward geocoding) converts a human-readable address (e.g. 260 Elizabeth Street, Melbourne VIC 3000) into geographic coordinates (e.g. latitude -37.81384, longitude 144.963028) which can be used to place markers on a map or to position the map.
  • Reverse geocoding converts geographic coordinates into a human-readable address.
  • Geocode service providers include:
    • Google
    • Geocode.Farm
    • Vicmap
    • PSMA
    • psmafarm.
  • Each geocode service is defined by a set of name/value pair fields, some required, some optional.

 

2 "Google" Geocode Service

go-to-typical-definition-2

2.1 Definition

The Google Geocode Service is defined by a set of name/value pair fields consisting of:

  • Required fields
  • Optional fields

Note:

  1. Default values for the fields described in the tables below are shown in bold text.

2.1.1 Required Fields

Field Valid Values Description
apiKey API key Your API key for both Google forward and reverse geocoding.
autocompleteUrl url url for Google forward geocoding.
geocodeUrl url url for Google reverse geocoding.
name google Geocode Service name.

2.1.2 Optional Fields

Field Valid Values Description
geocoderDefaultCountry Valid country code Used to improve forward geocoding performance. E.g. address searches will restrict results to the defined country.
To avoid conflicts, recommend using either the component's "country" field or this "geocoderDefaultCountry" field to specify a country, but not both.
Defaults to search all countries.
geocoderDefaultState Valid State code Used to improve forward geocoding performance. E.g. address searches will restrict results to the defined state.
Defaults to search all states.

2.2 Typical Definition

Below is a typical Google Geocode Service definition, defined with its required fields plus any optional field whose value is typically other than its default value.

    "geocodeSearchService": [
        {
            "apiKey": "insert your Google API key here",
            "autocompleteUrl": "https://maps.googleapis.com/maps/api/place/autocomplete/json?input=",
            "geocodeUrl": "https://maps.googleapis.com/maps/api/geocode/json?latlng=",
            "name": "google"
        }
    ]

One or more of the optional fields shown below can be included in the above definition should a value other than their default value be required.

            "geocoderDefaultCountry": "Australia",
            "geocoderDefaultState": "VIC",

 

3 "Geocode.Farm" Geocode Service

go-to-typical-definition-2

3.1 Definition

The Geocode.Farm Geocode Service is defined by a set of name/value pair fields consisting of:

  • Required fields
  • Optional fields

Note:

  1. Default values for the fields described in the tables below are shown in bold text.

3.1.1 Required Fields

Field Valid Values Description
apiKey API key. Your API key for both Geocode.Farm forward and reverse geocoding.
autocompleteUrl url url for Geocode.Farm forward geocoding.
geocodeUrl url url for Geocode.Farm reverse geocoding.
name geocodefarm Geocode Service name.

3.1.2 Optional Fields

Field Valid Values Description
geocoderDefaultCountry Valid country code Used to improve forward geocoding performance. E.g. address searches will restrict results to the defined country.
To avoid conflicts, recommend using either the component's "country" field or this "geocoderDefaultCountry" field to specify a country, but not both.
Defaults to search all countries.
geocoderDefaultState Valid State code Used to improve forward geocoding performance. E.g. address searches will restrict results to the defined state.
Defaults to search all states.

3.2 Typical Definition

Below is a typical Geocode.Farm Geocode Service definition, defined with its required fields plus any optional field whose value is typically other than its default value.

    "geocodeSearchService": [
        {
            "apiKey": "insert your geocode.farm API key here",
            "autocompleteUrl": "https://www.geocode.farm/v3/json/forward/?addr=",
            "geocodeUrl": "https://www.geocode.farm/v3/json/reverse/",
            "name": "geocodefarm"
        }
    ]

One or more of the optional fields shown below can be included in the above definition should a value other than their default value be required.

            "geocoderDefaultCountry": "Australia",
            "geocoderDefaultState": "VIC",

 

4 "Vicmap" Geocode Service

go-to-typical-definition-2

4.1 Definition

Vicmap provides authoritative location data for the Australian State of Victoria.

The VicMap Geocode Service is defined by a set of name/value pair fields consisting of:

  • Required fields
  • Optional fields

4.1.1 Required Fields

Field Valid Values Description
apiKey API key. Your API key for both Vicmap forward and reverse geocoding.
autocompleteUrl url url for Vicmap forward geocoding.
geocodeUrl url As Vicmap does not support reverse geocoding, use:
url for geocode.farm reverse geocoding.
name vicmap Geocode Service name.

4.2 Typical Definition

Below is a typical Vicmap Geocode Service definition, defined with its required fields.

    "geocodeSearchService": [
        {
            "apiKey": "Insert your Vicmap API Key here",
            "autocompleteUrl": "https://services.land.vic.gov.au/basemaps/map/addressSearch?jsoncallback=?&format=json&addressLine=",
            "geocodeUrl": "https://www.geocode.farm/v3/json/reverse/",
            "name": "vicmap"
        }
    ]

 

5 "PSMA" Geocode Service

go-to-typical-definition-2

5.1 Definition

PSMA provides authoritative location data for Australia.

PSMA Geocode Service is defined by a set of name/value pair fields consisting of:

  • Required fields
  • Optional fields

Note:

  1. Default values for the fields described in the tables below are shown in bold text.

5.1.1 Required Fields

Field Valid Values Description
addressUrl url url for PSMA reverse geocoding, used in conjuction with the geocodeUrl field.
Retrieves the full address details upon the geocodeUrl field retrieving partial details.
apiKey API key Your API key for PSMA forward geocoding.
apiKeyReverse API key Your API key for PSMA reverse geocoding.
autocompleteUrl url url for PSMA forward geocoding.
geocodeUrl url url for PSMA reverse geocoding.
name psma Geocode Service name.
radius Integer Radius in metres from the click point to search for & return addresses in order of closeness.

5.1.2 Optional Fields

Field Valid Values Description
enableReverseRadiusDisplay true Display a circle around the click point to show the address search range.
Primarily used for debugging.
false Default value.
reverseNoAddressIncrement Integer Number of metres to expand the search radius by if an address search returns zero addresses.
0 Default value.
reverseNoAddressRetry Integer The number of times to expand the search radius if an address search returns zero addresses.
0 Default value.
showReverseAddressPoint Integer The number of closest points returned by an address search to mark with an icon numbered in order of closeness. Primarily used for debugging.
0 Default value.

5.2 Typical Definition

Below is a typical PSMA Geocode Service definition, defined with its required fields plus any optional field whose value is typically other than its default value.

    "geocodeSearchService": [
        {
            "apiKey": "Insert your PSMA API Key here",
            "apiKeyReverse": "Insert your Reverse PSMA API Key here",
            "addressUrl": "https://api.psma.com.au/predictive/address/",
            "autocompleteUrl": "https://api.psma.com.au/predictive/address?query=",
            "geocodeUrl": "https://api.psma.com.au/v2/addresses?radius=",
            "name": "psma"
        }
    ]

One or more of the optional fields shown below can be included in the above definition should a value other than their default value be required.

            "enableReverseRadiusDisplay": true,
            "reverseNoAddressIncrement": 20,
            "reverseNoAddressRetry": 2,
            "showReverseAddressPoint": 5,

 

6 "psmafarm" Geocode Service

go-to-typical-definition-2

6.1 Definition

psmafarm is a hybrid Geocode Service in that it uses PSMA for forward geocoding and Geocode.Farm for reverse geocoding.

psmafarm Geocode Service is defined by a set of name/value pair fields consisting of:

  • Required fields
  • Optional fields

6.1.1 Required Fields

Field Valid Values Description
apiKey API key Your API key for PSMA forward geocoding.
apiKeyReverse API key Your API key for Geocode.Farm reverse geocoding.
autocompleteUrl url url for PSMA forward geocoding.
geocodeUrl url url for Geocode.Farm reverse geocoding.
name psmafarm Geocode Service name.

6.1.2 Optional Fields

Field Valid Values Description
geocoderDefaultState Valid State code Used to improve forward geocoding performance. E.g. address searches will restrict results to the defined state.
Defaults to search all states.

6.2 Typical Definition

Below is a typical psmafarm Geocode Service definition, defined with its required fields.

    "geocodeSearchService": [
        {
            "apiKey": "Insert your PSMA API Key here",
            "apiKeyReverse": "Insert your Reverse PSMA API Key here",
            "autocompleteUrl": "https://api.psma.com.au/predictive/address?query=",
            "geocodeUrl": "https://www.geocode.farm/v3/json/reverse/",
            "name": "psmafarm"
        }
    ]

One or more of the optional fields shown below can be included in the above definition should a value other than their default value be required.

            "geocoderDefaultState": "VIC",