Geocode statement - MapBasic - 2023

Purpose

Geocodes a table or individual value using a remote geocode service through a connection created using the Open Connection statement and set up using the Set Connection Geocode statement. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Geocode connection_number 
	Input 
		[ Table input_tablename ]
		[ Country = Country_expr 
			[ Street = Street_expr, 
				[ IntersectingStreet = IntersectingStreet_expr ], 
				Municipality = Municipality_expr, 
				CountrySubdivision = CountrySubdiv_expr, 
				PostalCode = PostalCode_expr, 
				CountrySecondarySubdivision = CountrySecondarySubdiv_expr, 
				SecondaryPostalCode = SecondaryPostalCode_expr, 
				Placename = Placename_expr,
				Street2 = Street2_expr,
				MunicipalitySubdivision = MunicipalitySubdiv_expr ] ]
				[ PassThrough name value, name value, ...  ]
	Output 
		[ Into 
			[ Table out_tablename [ Key out_keycolumn = in_keyexpr ] ] |
			[ Variable variable_name ] ]
		[ Point [ On | Off ] [ Symbol Symbol_expr ], ] 
		[ Street_column = Street, 
			Municipality_column = Municipality,
			CountrySubdiv_column = CountrySubdivision,
			PostalCode_column = PostalCode,
			CountrySecondarySubdiv_column = CountrySecondarySubdivision,
			SecondaryPostalCode_column = SecondaryPostalCode,
			Placename_column = Placename,
			MunicipalitySubdiv_column = MunicipalitySubdivision,
			Country_column = Country, 
			ResultCode_column = ResultCode,
			Latitude_column = Latitude, 
			Longitude_column = Longitude 
			Columns colname = geocoder_keyname [ , ] ... ] 
		[ Interactive [ On 
			[ Max Candidates candidates_expr | All ] 
			[ CloseMatchesOnly [ On | Off ] ]
			| Off [ First | None ] ] ]

connection_number is the number returned when the connection was created. See Open Connection statement.

input_tablename is a table alias of an open table including result sets and selections.

Country_expr is a string expression representing the three letter ISO code for the country.

Street_expr is an expression that specifies a street address.

IntersectingStreet_expr is an expression that specifies a street that should intersect with the street specified in Street_expr.

Municipality_expr is an expression that specifies the name of a municipality.

CountrySubdivision_expr is an expression that specifies the name of a subdivision of a country. For example, in the US this specifies the name of a state. In Canada it specifies the name of a province.

PostalCode_expr is an expression that specifies a postal code.

CountrySecondarySubdiv_expr is an expression that specifies the name of a secondary subdivision for a country. For example, in the US this corresponds to a county, in Canada this corresponds to a census division.

SecondaryPostalCode_expr is an expression that specifies a secondary postal code system. In the US this corresponds to a ZIP+4 extension on a ZIP Code.

Placename_expr is an expression that specifies the name of a well-known place, such as a large building that may contain multiple addresses.

Street2_expr is an expression that specifies a secondary address line.

MunicipalitySubdiv_expr is an expression that specifies the name of a municipality subdivision.

out_tablename is a table alias of a table to be used as the holder of the data resulting from the geocode operation.

out_keycolumn is a string representing the name of a key column in the output table that will be used to hold some identifying "key" from the input records. This is used to identify the record from where the geocode came.

in_keyexpr is an expression from (the input table) whose value is inserted in the output record.

variable_name is the name of a variable that can hold a single geometry.

Symbol_expr is an expression that specifies the symbol to use when displaying a Point from the geometry column. See Symbol clause for more information.

Street_column is an alias that represents the name of the column to hold the Street result.

Municipality_column is a string the represents the name of the column to hold the Municipality result.

CountrySubdiv_column is a string the represents the name of the column to hold the Country Subdivision result.

PostalCode_column is a string the represents the name of the column to hold the Postal Code result.

CountrySecondarySubdiv_column is a string the represents the name of the column to hold the Country Secondary Subdivision result.

SecondaryPostalCode_column is a string the represents the name of the column to hold the Secondary Postal Code result.

Placename_column is a string the represents the name of the column to hold the Placename result.

MunicipalitySubdiv_column is a string the represents the name of the column to hold the Municipality Subdivision result.

Country_column is a string the represents the name of the column to hold the Country result.

ResultCode_column is a string the represents the name of the column to hold the Result Code generated by the geocoder.

Latitude_column is a string the represents the name of the float or decimal column to hold the Latitude result.

Longitude_column is a string the represents the name of the float or decimal column to hold the Longitude result.

colname is a string the represents the name of the column for a geocoder-specific result.

geocoder_keyname is a string representing the name of a country-specific geocoder item. These items are documented by the specific geocoder.

candidates_expr is an expression that specifies the number of candidates to be returned in an interactive geocoding session.

Description

Every Geocode statement must include an Input clause and an Output clause. The input_tablename is optional, however if a table is not specified, the resulting geocode operation would be performed on a set of string inputs (variables or constants), so that only a single address is geocoded in each request. The output_tablename is also optional. See Table vs. non-table- based input and output below.

Input clause

The Input clause is required as a geocode request needs some input data.

A Country must be specified either as an explicit argument or as a column in input_tablename. When a single country is used, it can be a constant string if no data is available. ISO standard three letter country codes must be used.

The list of fields to include from input_table to be geocoded must include at least one value. The more expressions that are included, the more accurate your geocoding result will be.

PassThrough is a set of name/value pairs that are sent to the geocoder. These pairs are geocode service and country specific and are documented by the particular geocode service. For now, this is only used by "Global Geocoder" and "Precisely Global Geocoder".

Output clause

The Output clause is required, as without it, the entire command returns nothing.

Into Table indicates that the Output clause refer to columns in output_table, which must be writable. If not specified, the clauses refer to the input_table. Note that if the input columns are to be updated, they must be specified both for input AND output.

Key is used with Into Table. This clause creates a relationship between the key columns in the input and output table.

Variable specifies that the geometry result from the geocode operation is stored in a variable defined in variable_name. When using this output option, note that if the input is a table only the first record is processed and the remainder of the records are skipped.

Point specifies that the geographic result of the geocode is to be stored in either the table or the variable. In the case of a table, this requires that the table be mappable.

To store the point stored into the object column, specify Point or Point On (default is on). The current default symbol is used. To return the same using a specific symbol, specify Point On Symbol symbol_expr. If you do not want to store the point in the object column, specify Point Off. Whether you want the object created or not, you can still store the x and y values in real number columns. To do this specify those columns as Latitude = latitude_column Longitude = longitude_column.

The rest of the output data specifies columns in the output table where well known geocoder return values are stored. In general, these may be more specific than the input. For example, it may be possible to geocode an address with just a business name of "MapInfo" and a post code of "12180". However, much more is returned in the output. The Columns extension allows for data to be returned that is geocoder specific. The user must know the names of the keys as defined by the geocoders.

Table vs. non-table- based input and output

The Geocode statement can be used with any combination of table-based and non-table-based inputs and outputs. If you choose to use a table-based input you can have your output placed into either a new or existing table, or into a variable. If the output is a variable then only the first record is processed and the only value stored is the geographic object.

If you choose non-table-based input, the values for the operation must either be expressions (not column names), variables, or constant strings, the output can be placed either into a table or assigned to a variable.

Interactive clause

Interactive [ On | Off ] is an optional keyword that controls whether a dialog box to be displayed in the case of multiple candidates returned for each address. When this occurs, the user is prompted to choose, respecify, skip, or cancel the operation.

is asked to decide which of the choices is best given the opportunity to skip this input. When On, the dialog box displays in these situations. When Off, if multiple matches occur the choices are to accept the first candidate or none, meaning that the record is skipped. The default is skipping the record.

If the Interactive keyword is not included, it is equivalent to Interactive Off None and no options can be specified. If Interactive is specified, the default is On.

• Interactive is equivalent to Interactive On. When no value is provided for Max the default is three (3) candidates to be returned.
• Interactive On Max Candidates All returns all candidates
• Interactive On Max Candidates 4* myMBVariable/6 returns the number of candidates resulting from the evaluation of the expression.
• Interactive Off is equivalent to Interactive Off None.
• Interactive Off First returns the first candidate in the list.

The CloseMatchesOnly setting sets the geocode service to only return close matches as defined by the server. If CloseMatchesOnly is set to Off, all results are returned up to the number defined in Max Candidates with the ones that are considered to be close marked as such.

Examples

The following example shows a geocode request using the nystreets table and specifying the use of the city, Streetname, state, and postalcode.

Geocode connectionHandle Input Table nystreets municipality=city, 
street=StreetName, countrysubdivision=state, postalcode=zip, 
country="usa"
OUTPUT StreetName=street, address=municipality

This example shows a geocode request using the nystreets table and specifying a symbol for displaying the output.

Geocode connectionHandle Input Table nystreets street=StreetName, 
country="usa" 
Output Point Symbol MakeFontSymbol(65, 255 ,24,"MapInfo 
Cartographic",32,0), StreetName=street

This example sends a request with the Interactive set to On with the return value being placed into the street column.

Geocode connectionHandle Input Table nystreets street=StreetName, 
country="usa" 
Output Point Symbol MakeFontSymbol(65, 255 ,24,"MapInfo 
Cartographic",32,0), 
StreetName=street Interactive on Max Candidates 5

The following example shows a Geocode request without using a table and outputting the results into a variable:

Geocode connectionHandle Input street="1 Global View", country="usa", 
countrysubdivison="NY", municipality="Troy" 
Output Variable outvar

See Also:

Open Connection statement