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

2.1 Definition

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

Required fields
Optional fields

Note:

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

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:

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

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

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:

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

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
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 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": [
        {
            "addressUrl": "https://api.psma.com.au/predictive/address/",
            "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",