Candidate Return Information

The standard set of fields that may be returned includes:

• Total matches
• Total possible candidates
• Candidate address
• Candidate range
• Matched fields
• Geocode coordinates (for geocoding operation)
• Result codes

The return of some of these fields may depend on the type of data provided in the configured geocoding dataset(s). Refer to each country's section for information on the available output fields and their definitions. In addition, there are some countries that have custom output fields. Refer to each country's section in Appendix A - Country-Specific Information for information on the available custom output fields.

You also have the option to specify additional return information, such as:

• The maximum number of candidates to be returned.
• Whether to return all available information for each candidate or to return only specific address fields. These additional fields are specified using the returnFieldsDescriptor. The following options are available:
  • returnMatchDescriptor - Returns the match descriptor object, which indicates the parts of the candidate that matched the input address.
  • returnStreetAddressFields - Returns all of the individual street fields that make up the formattedStreetAddress field separately, such as the base part of the main address, the thoroughfare type, any pre- and/or post-directionals, etc.
  • returnUnitInformation - Where available, returns unit type and unit value information separately in the unitType and unitValue fields, as well as in the formattedStreetAddress field.
  • returnAllCustomFields - Returns all of the custom fields for the candidate.
  • returnedCustomFieldKeys - Specifies a list of keys that represent the custom fields to be returned in the candidate's customFields output. For example: “CTYST_KEY” or “DATATYPE”.
    Note: To specify multiple key/value pairs for a country, use spaces to separate the names of the custom fields to be returned. Candidates which have the field information available will include the custom fields with the keys in the candidate's customFields output.

    For example in a REST JSON request:

    "preferences" : {
        "customPreferences" : {
          "USA.returnedCustomFieldKeys" : "LAT LON SHORT_CITY"
        }
    }

    Note: Custom fields vary by country. To locate your country's information, refer to Country-Specific Information to find the corresponding section in the appendix that provides more details.

Specifying Additional Candidate Return Information in the REST API

For more information, see Geocode POST Request.