Geocoding
|
|
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.
|
|
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
|
|
getLocationsList
|
|
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
|
|
|
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 |
R�gion & Province |
|
| Switzerland |
Kanton |
|
| Czech Republic |
Kraj (r�gion) |
|
| Germany |
Land, Freistaat, Freie und Hansestadt |
|
| Denmark |
Amt, F�r�erne |
|
| Spain |
Ciudad aut�noma de Melilla, Ciudad aut�noma de Ceuta, Comunidade aut�noma, Provincia |
|
| Finland |
L��ni |
|
| France |
R�gion, R�gion mono-d�partementale |
D�partement |
| Northern Ireland |
Local Government District |
|
| Ireland |
County County Borough |
|
| Italy |
Regione |
Provincia |
| Monaco |
Commune |
|
| Netherlands |
Provincie |
|
| Norway |
Fylke |
|
| Poland |
Wojew�dztwo |
|
| Portugal |
Regi�o aut�noma, Distrito |
|
| San Marino |
Pas de subdivision |
|
| Sweden |
L�n |
|
| Canada |
Province, Territoire |
|
| United States of America |
State Federal district |
|
|
|
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 |
| Northern Mariana Islands |
MNP |
| Norway |
NOR |
| Oman |
OMN |
| Pakistan |
PAK |
| Palau |
PLW |
| Panama |
PAN |
| Papua New Guinea |
PNG |
| Paraguay |
PRY |
| Peru |
PER |
| Philippines |
PHL |
| Pitcairn Islands |
PCN |
| Poland |
POL |
| Portugal |
PRT |
| Puerto Rico |
PRI |
| Qatar |
QAT |
| Reunion |
REU |
| Romania |
ROU |
| Russia |
RUS |
| Rwanda |
RWA |
| Saint Helena |
SHN |
| Saint Kitts and Nevis |
KNA |
| Saint Lucia |
LCA |
| Saint Pierre and Miquelon |
SPM |
| Saint Vincent and the Grenadines |
VCT |
| Samoa |
WSM |
| San Marino |
SMR |
| S�o Tom� and Pr�ncipe |
STP |
| Saudi Arabia |
SAU |
| Senegal |
SEN |
| Serbia and Montenegro |
SCG |
| Seychelles |
SYC |
| Sierra Leone |
SLE |
| Singapore |
SGP |
| Slovakia |
SVK |
| Slovenia |
SVN |
| Solomon Islands |
SLB |
| Somalia |
SOM |
| South Africa |
ZAF |
| South Georgia and the South Sandwich Islands |
SGS |
| South Korea |
KOR |
| Spain |
ESP |
| Sri Lanka |
LKA |
| Sudan |
SDN |
| Suriname |
SUR |
| Swaziland |
SWZ |
| Sweden |
SWE |
| Switzerland |
CHE |
| Syria |
SYR |
| Taiwan |
TWN |
| Tajikistan |
TJK |
| Tanzania |
TZA |
| Thailand |
THA |
| Timor-Leste |
TLS |
| Togo |
TGO |
| Tokelau |
TKL |
| Tonga |
TON |
| Trinidad and Tobago |
TTO |
| Tunisia |
TUN |
| Turkey |
TUR |
| Turkmenistan |
TKM |
| Turks and Caicos Islands |
TCA |
| Tuvalu |
TUV |
| Uganda |
UGA |
| Ukraine |
UKR |
| United Arab Emirates |
ARE |
| United Kingdom |
GBR |
| United States of America |
USA |
| Uruguay |
URY |
| Uzbekistan |
UZB |
| Vanuatu |
VUT |
| Vatican City (Holy See) |
VAT |
| Venezuela |
VEN |
| Vietnam |
VNM |
| Virgin Islands |
VIR |
| Wallis and Futuna |
WLF |
| Western Sahara |
ESH |
| Yemen |
YEM |
| Zambia |
ZMB |
| Zimbabwe |
ZWE |
|
 |
