# Global Express Free Form

The GlobalExpressFreeForm service is provided as a means of retrieving all available address elements using a free form search.

Endpoint: GET /GlobalExpressFreeForm

## Header parameters:

  - `Accept` (string, required)
    Format of the response.
    Enum: "application/json", "*/*"

  - `Content-Type` (string, required)
    Format of the request.
    Enum: "application/json", "application/xml"

## Query parameters:

  - `cols` (string)
    Columns - Entering the column name will return the column. Specifying a group name will return all columns in the group.
Delimit multiple columns with a ,.
- gbextras - GB Only. Return UPRN (SourceID) and UDPRN (SupplierID) values for each address. These will be in the Extras element.
- results - US Only. Return Address Object result codes for each address in the Extras field. For example, a USPS only address will return "AddrObjectResultCode": "AS01".
    Enum: "gbextras", "results"

  - `diacriticreplace` (boolean)
    True replaces diacritics in the address. False will keep current diacritics in the address results. If left blank, this defaults to False.
    Enum: true, false

  - `format` (string)
    Desired format of the response. Possible values are json, jsonp, or xml, depending on the endpoint.

Note: the base URL for JavaScript format request is https://expressentry.melissadata.net/jsonp/.
    Enum: "xml", "json", "jsonp"

  - `id` (string, required)
    Required. The License Key issued by Melissa.
    Example: "{REPLACE-WITH-YOUR-LICENSE-KEY}"

  - `maxrecords` (number)
    The maximum number of records to return.
    Example: 20

  - `nativecharset` (boolean)
    True, False, or blank.
When set to True, return results in the native character set for the country.
When set to False, return transliterated results in the Latin character set.
When set to blank &nativecharset=, return results in the input character set.
    Enum: true, false

  - `opt` (string)
    Options to modify the output.
- poboxes: -  true will allow P.O. Boxes and military addresses to be returned with U.S. Addresses.
    Example: "poboxes:true"

  - `country` (string, required)
    Required. The ISO2Code or country name of the address.
    Example: "US"

  - `ff` (string, required)
    Required. The free form address, with search terms delimited by %20 or a space.
    Example: "22382+Avenida+Empresa,+Rancho+Santa+Margarita,+CA+92688"

## Response 200 fields (application/json):

  - `Version` (string)
    The current service version number.

  - `ResultCode` (string)
    Lists result codes for the most recent request. For more information, see [Global Express Entry Result Codes](https://docs.melissa.com/cloud-api/global-express-entry/result-codes.html).

  - `ErrorString` (string)
    Lists error codes from any errors caused by the most recent request. For more information, see [Global Express Entry Result Codes](https://docs.melissa.com/cloud-api/global-express-entry/result-codes.html).

  - `Results` (array)
    Array with Address array(s) containing the record level fields.

  - `Results.Address` (object)

  - `Results.Address.Address` (string)
    The full address in one line.

  - `Results.Address.Address1` (string)
    Address line 1.

  - `Results.Address.Address2` (string)
    Address line 2.

  - `Results.Address.Address3` (string)
    Address line 3.

  - `Results.Address.Address4` (string)
    Address line 4.

  - `Results.Address.Address5` (string)
    Address line 5.

  - `Results.Address.Address6` (string)
    Address line 6.

  - `Results.Address.Address7` (string)
    Address line 7.

  - `Results.Address.Address8` (string)
    Address line 8.

  - `Results.Address.Address9` (string)
    Address line 9.

  - `Results.Address.Address10` (string)
    Address line 10.

  - `Results.Address.Address11` (string)
    Address line 11.

  - `Results.Address.Address12` (string)
    Address line 12.

  - `Results.Address.DeliveryAddress` (string)
    The full delivery address in one line.

  - `Results.Address.DeliveryAddress1` (string)
    Delivery address line 1.

  - `Results.Address.DeliveryAddress2` (string)
    Delivery address line 2.

  - `Results.Address.DeliveryAddress3` (string)
    Delivery address line 3.

  - `Results.Address.DeliveryAddress4` (string)
    Delivery address line 4.

  - `Results.Address.DeliveryAddress5` (string)
    Delivery address line 5.

  - `Results.Address.DeliveryAddress6` (string)
    Delivery address line 6.

  - `Results.Address.DeliveryAddress7` (string)
    Delivery address line 7.

  - `Results.Address.DeliveryAddress8` (string)
    Delivery address line 8.

  - `Results.Address.DeliveryAddress9` (string)
    Delivery address line 9.

  - `Results.Address.DeliveryAddress10` (string)
    Delivery address line 10.

  - `Results.Address.DeliveryAddress11` (string)
    Delivery address line 11.

  - `Results.Address.DeliveryAddress12` (string)
    Delivery address line 12.

  - `Results.Address.CountryName` (string)
    The name of the country.

  - `Results.Address.ISO3166_2` (string)
    The 2 letter ISO 3166 country code value. For example: US for United States or CA for Canada.

  - `Results.Address.ISO3166_3` (string)
    The 3 letter ISO 3166 country code value. For example: USA for United States or CAN for Canada.

  - `Results.Address.ISO3166_N` (string)
    The ISO 3166 country number value. For example: 840 for United States or 124 for Canada.

  - `Results.Address.SuperAdministrativeArea` (string)
    A region within a country that has a higher level of administrative control or governance than other areas.

  - `Results.Address.AdministrativeArea` (string)
    State, Province. This is a common geographic area unit for larger countries.

  - `Results.Address.SubAdministrativeArea` (string)
    County. A logical area that that is smaller than the administrative area but larger than a locality. Rarely used as part of an official address.

  - `Results.Address.Locality` (string)
    City, Town. The most common geographic area, used by virtually all countries.

  - `Results.Address.CityAccepted` (string)
    A list of accepted city names.

  - `Results.Address.CityNotAccepted` (string)
    Any non-accepted city names will be included in this field.

  - `Results.Address.DependentLocality` (string)
    Urbanization. A dependent locality is a logical area unit that is smaller than a locality but larger than a double dependent locality or thoroughfare. It can often be associated with a neighborhood or sector.

  - `Results.Address.DoubleDependentLocality` (string)
    A logical area unit that is smaller than a dependent locality but bigger than a thoroughfare. This field is rarely used.

  - `Results.Address.Thoroughfare` (string)
    Street. The most common street or block data element.

  - `Results.Address.DependentThoroughfare` (string)
    Dependent Street. A second thoroughfare that is required to narrow down the final address. This is rarely used.

  - `Results.Address.Building` (string)
    A descriptive name identifying an individual location.

  - `Results.Address.Premise` (string)
    Street Number. The premise identifying number.

  - `Results.Address.SubBuilding` (string)
    A smaller division of a building. For example, if an address has a building name that is a part of a larger set of buildings, then the sub building may be populated.

  - `Results.Address.PostalCode` (string)
    ZIP Code. Complete postal code for a particular delivery point.

  - `Results.Address.PostalCodePrimary` (string)
    The primary portion of the postal code. In the US, this is a 5-digit ZIP code.

  - `Results.Address.PostalCodeSecondary` (string)
    The secondary portion of the postal code. In the US this is the +4 of the ZIP code.

  - `Results.Address.Organization` (string)
    Business, Company. This name of the organization.

  - `Results.Address.PostBox` (string)
    Post box information for a particular delivery point.

  - `Results.Address.Unmatched` (string)
    Any part of the address that did not match other fields will be saved in this field.

  - `Results.Address.GeneralDelivery` (string)
    The USPS address type assigned for the address.

  - `Results.Address.DeliveryInstallation` (string)
    Canada Only. The delivery installation for the address.

  - `Results.Address.Route` (string)
    Canada Only. The route service number.

  - `Results.Address.AdditionalContent` (string)
    Any additional content associated with the address.

  - `Results.Address.CountrySubdivisionCode` (string)
    This is the ISO3166-2 code for country subdivisions, usually the administrative area for a country. The format is the 2 letter country code followed by a dash followed by 2 or 3 characters or two numbers.

  - `Results.Address.MAK` (string)
    Melissa Address Key. A unique key assigned to the submitted address.

  - `Results.Address.BaseMAK` (string)
    Melissa Address Key Base. If the address has suites or apartments the 10 digit proprietary BaseMAK will be returned and correspond to the overall building.

  - `Results.Address.Latitude` (string)
    The latitude geographic coordinate of the output address.

  - `Results.Address.Longitude` (string)
    The longitude geographic coordinate of the output address.

  - `Results.Address.DistanceFromPoint` (integer)
    The distance in miles from the specified point.

  - `Results.Address.Extras` (object)
    This element will be returned, depending on which additional columns are specified.

  - `Results.Address.Extras.UDPRN` (string)
    GB Only. The Unique Delivery Point Reference Number issued by Royal Mail. This is an 8-digit unique number.

  - `Results.Address.Extras.UPRN` (string)
    GB Only. The Unique Property Reference Number issued by Royal Mail. This is a number unique to each address in GB. This is a unique number up to 12-digits long.

  - `Results.Address.Extras.AddrObjectResultCode` (string)
    US Only. Address Object result code indicates the level of match for the address.

## Response 400 fields (application/json):

  - `type` (string)
    The type of error that occurred.

  - `title` (string)
    A short summary of the error.

  - `status` (integer)
    The HTTP status code for the error.

  - `errors` (object)

  - `errors.$.<PropertyName>` (array)
    A detailed message about the error.

  - `traceId` (string)
    A unique identifier for the request, useful for debugging.