VIAMICHELIN SOAP API


Geocoding

Overview

 

The Geocoding Web Service allows you to enter an address and obtain an ordered list of locations with an address description and the associated WGS84 encoded geographic coordinates.


WSDL

The WSDL (Web Services Description Language) describes the behaviour of the Web Service and instructs how to interact with it. It appears as an XML formatted file for each VIAMICHELIN SOAP API Service. 

You can consult the «Geocoding» WSDL file at the following URL: 
http://webservices.viamichelin.com/ws2/services/Geocoding?wsdl

This file is also included in the «Ressources\WSDL» sub-directory in the SDK

Defined methods

getLocationsList

getLocationsList method


Description 

This method takes a list of addresses and finds the corresponding locations. 

 

Specifications 

  • The maximum number of items in the list of supplied addresses is 50. Beyond this limit, a SOAP fault is returned.
  • The minimum number of items in the list of supplied addresses cannot be lower than 1. Otherwise, a SOAP fault is returned.
  • The maximum returned values per address is 30.
  • The geographic coordinates used are WGS84 encoded.

Input Parameters 

 Parameter  Mandatory  Description
request
(GeocodingRequest)
true Specifies the addresses list to «geocode» and the «geocoding» method which should be used.
authenticationParams
(String)
true Specifies an authentication identifier for accessing Web Service : login + '|' character + password

Output Parameter 

 Parameter  Description
FoundLocationList[ ] Array of found locations even if no locations are found.

Use 

The Web Service allows you to search the geographic coordinates for one or several addresses using the GeocodingRequest which defines a list of valid addresses (see InputAddress). 

To be valid, an InputAddress must have at least one of the following attributes defined:
  • address: required if postalCode and cityName attributes are not defined.
  • cityName: required if postalCode and address attributes are not defined.
  • postalCode: required if cityName and address attributes are not defined.
  • countryCode: required field.

Then, for each supplied address, a FoundLocationList is returned; it contains a list of all locations (geographic coordinates, complete address description) matching the supplied address. 

The Geocoding service interacts with the following ViaMichelin SOAP API:
  • MapManagement Web Services: you can use the geocoding results (geographic coordinates or location/place identifier) in these services so as to display them on a map.
  • FindPOI Web Service: you can use the geocoding result (geographic coordinates) so as to get the list of POI located around a given location.
  • RouteCalculation Web Service: you can use the geocoding result (geographic coordinates or location/place identifier) so as to specify the departure and the arrival points and even stage points when calculating a route.

Notes 

This Web service billing is not based on the number of successful requests received but on the number of individual treatments made by ViaMichelin. A treatment is defined as the calculation of each element in the table named «addressesList» per request even if a result is not obtained.
Using the Geocoding Web Service, you can obtain the following location type:
  • City,
  • Street,
  • specific POI (monuments, Subway stations, Railway stations, ...),

In order to limit the search, you can use the «StateName» attribute as it allows you to specify the administrative area in which the search has to be performed.
In this version a new option is available which includes a «geocoding mode» especially suitable for mobile devices. It can geocode a supplied addresses with a reduced number of characters. 

When this mode is activated (see «mode» attribute defined in GeocodingRequest), the Geocoding Web Service is searching for locations corresponding to the supplied addresses in two steps:
  • Step one: Geocoding Web Service is searching the locations corresponding exactly to the supplied addresses the same way as «normal» Mode.
  • Step two: If no location was found in step one, the Geocoding Web Service adds 'Wildcards' to the characters strings which exceed three characters and searches for corresponding locations.

For example, with a supplied address defined by:
  • address: Welli
  • cityName: Westm
  • countryCode: GBR
The Geocoding Web Service will start to search for locations corresponding exactly to the supplied address. But in this case no location will be found. 
Then the Geocoding Web Service will apply a «Wildcards search». That means that the supplied address will be considered as:
  • address: Welli*
  • cityName: Westm*
  • countryCode: GBR
Then 6 locations will be found and returned:
  • «Wellington Close, Westminster»
  • «Wellington Court, Westminster»
  • «Wellington Place, Westminster»
  • «Wellington Road, Westminster»
  • «Wellington Street,Westminster»
  • «Duke Of Wellington Place, Westminster»

Errors 

 Error code  Description  Possible problems
200 Invalid request - request value is not defined (null)
201 Invalid addresses list - the list of supplied addresses is not defined (null)
- the list of supplied addresses is empty
- the list of supplied addresses contains more that 200 items.
201 Invalid «geocoding mode» - supplied «geocoding mode» value is not available.
3 Abnormal service termination - internal problem

Code sample (Java)
// geocoding request initialization 
GeocodingRequest request = new GeocodingRequest(); 
InputAddress[] addressList = new InputAddress[1]; 
InputAddress address = new InputAddress(); 
address.setAddress("18 rue de Vaugirard"); 
address.setCityName("Paris"); 
address.setCountryCode("FRA"); 
address.setPostalCode(null); 
address.setStateName(null); 
addressList[0] = address; 
request.setAddressesList(addressList); 
// invoke geocoding web service
GeocodingServiceLocator locator = new GeocodingServiceLocator(); 
Geocoding service = locator.getGeocoding(); 
FoundLocationList[] result = service.getLocationsList(request, "YOUR_LOGIN|YOUR_PASSWORD");

Code sample (VB.NET)
Will be available in a future version

Code sample (C#.NET)
Will be available in a future version


APPENDIX I

List of administrative areas available by country. «Administrative area» refers to each level of the administrative organization of the country. 
These administrative areas are used in the StateName field of InputAddress. 

 Countries  1st level  2nd Level
Andorra    
Austria Bundesland  
Belgium Region & Province  
Switzerland Kanton  
Czech Republic Kraj (region)  
Germany Land, Freistaat, Freie und Hansestadt  
Denmark Amt, Fereerne  
Spain Ciudad autenoma de Melilla, Ciudad autenoma de Ceuta, Comunidade autenoma, Provincia  
Finland Leeni  
France Region, Region mono-departementale Departement
Northern Ireland Local Government District  
Ireland County County Borough  
Italy Regione Provincia
Monaco Commune  
Netherlands Provincie  
Norway Fylke  
Poland Wojewedztwo  
Portugal Regieo autenoma, Distrito  
San Marino Pas de subdivision  
Sweden Len  
Canada Province, Territoire  
United States of America State Federal district  



APPENDIX II

List of available ISO country code.


 Denomination  ISO Code
Afghanistan AFG
Albania ALB
Algeria DZA
American Samoa ASM
Andorra AND
Anguilla AIA
Antarctica ATA
Antigua and Barbuda ATG
Argentina ARG
Armenia ARM
Australia AUS
Austria AUT
Azerbaijan AZE
Bahamas (The) BHS
Bahrain BHR
Bangladesh BGD
Barbados BRB
Belarus BLR
Belgium BEL
Belize BLZ
Benin BEN
Bermuda BMU
Bhutan BTN
Bolivia BOL
Bosnia and Herzegovina BIH
Botswana BWA
Bouvet Island BVT
Brazil BRA
British Indian Ocean Territory IOT
British Virgin Islands VGB
Brunei Darussalam BRN
Bulgaria BGR
Burkina Faso BFA
Burundi BDI
Cambodia CMR
Cameroon BGR
Canada CPV
Cape Verde CYM
Cayman Islands BGR
Central African Republic CAF
Chad TCD
Chile CHL
Christmas Island CXR
Cocos Island COL
Comoros COM
Congo COG
Costa Rica CRI
Croatia HRV
Cuba CUB
Cyprus CYP
Czech Republic CZE
Democratic Republic of the Cong COD
Denmark DNK
Djibouti DJI
Dominica DMA
Dominican Republic DOM
Ecuador ECU
Egypt EGY
El Salvador SLV
Equatorial Guinea GNQ
Eritrea ERI
Estonia EST
Ethiopia ETH
Falkland Islands FLK
Faroe Islands CUB
Fiji FJI
Finland FIN
France FRA
French Guiana GUF
French Polynesia PYF
French Southern and Antarctic Lands ATF
Gabon GAB
Gambia (The) GMB
Georgia GEO
Germany DEU
Ghana GHA
Gibraltar (linked to Spain) ESP
Greece GRC
Greenland GRL
Grenada GRD
Guadeloupe GLP
Guam GUM
Guatemala GTM
Guernsey (linked to GBR) GBR
Guinea GIN
Guinea-Bissau GNB
Guyana GUY
Haiti HTI
Heard Island and McDonald Islands HMD
Honduras HND
Hungary HUN
Iceland ISL
India GBR
IND GBR
Indonesia IDN
Iran IRN
Iraq IRQ
Ireland IRL
Israel ISR
Italy ITA
Ivory Coast CIV
Jamaica JAM
Jan Mayen SJM
Japan JPN
Jersey (linked to GBR) GBR
Jordan JOR
Kazakhstan KAZ
Kenya KEN
Kiribati KIR
Kuwait KWT
Kyrgyzstan KGZ
Laos LAO
Latvia LVA
Lebanon LBN
Lesotho LSO
Liberia LBR
Libya LBY
Liechtenstein LTU
Luxembourg LUX
Macedonia MKD
Madagascar MDG
Malawi MWI
Malaysia MYS
Maldives MDV
Mali MLI
Malta MLT
Man (Isle of) XIM
Marshall Islands MHL
Martinique MTQ
Mauritania MRT
Mauritius MUS
Mayotte MYT
Mexico MEX
Micronesia (Federated States of) FSM
Moldova MDV
Monaco MCO
Mongolia MNG
Montserrat MAR
Morocco MYT
Mozambique MOZ
Myanmar MMR
Namibia NAM
Nauru NRU
Nepal NPL
Netherlands NLD
Netherlands Antilles ANT
New Caledonia NCL
New Zealand NZL
Nicaragua NIC
Niger NER
Nigeria NGA
Niue NIU
Norfolk Island PRK
North Korea NIC