Daten-Schnittstellen: HTTP & XML Interfaces (optional) - Auslaufen mit 31.03.2018

 

Schnittstellen müssen vom Anbieter extra freigeschalten und aktiviert werden. Support, Änderungen und Wartung von Schnittstellen sind nicht im Standard inkludiert. Aufgrund der technischen Begriffe ist der Großteil der Dokumentation in Englisch gehalten.

 

 

Anlegen und Deaktivieren von Geofence-Bereichen - Auslaufen mit 31.03.2018

Die folgenden Aufrufe stehen bis auf weiteres zur Verfügung, eine Änderung in naher Zukunft ist aber geplant:

http://uat.sw-management.at/GFS/interfaces/Geocoding.jsp?secid=xml2050182512-3254981481565771034-3279775603942294823

 

Geofence erstellen

https://uat2.sw-management.at/GFS/ExternalXMLServlet?secid=xml5089085-3532047540225885415-6123629436725404139&operation=gfgeocoding&geofenceName=XLTest2&country=AUT&city=Albersdorf&street=Albersdorf%209&postalcode=8200

Geofences deaktivieren

http://uat.sw-management.at/GFS/ExternalXMLServlet?secid=xml2050182512-3254981481565771034-3279775603942294823&operation=activate_deactivate_geofence&geofenceName=XMLTest2&supop=deactivate


 

The interface to access that data is a http/xml interface. A simple http call can be used to get the data as an xml. In some cases an excel sheet can be uploaded and the server will fill in the missing data.

 

The communication is done as follows:

 

  • A http request is sent to the GPS Fleet Server, containing a security id and operation field
  • The gps fleet server checks if the client is authenticated and sends back the feedback

 

 

 

The following parameters have to be set at each request:

 

Paramname

Required

Example value

Comment

Operation

Yes

lastpos

The operation field defines what data has to be loaded

secid

yes

xml812089481

Please ask the GPS Fleet Software provider to get the security id. It is configured in the account and authorizes the caller to load certain data.

 

 

 

The Url to be called is the GPS Fleet Server url and /ExternalXMLServer

 

Example:

 

 http://gfs2.sw-management.at/GFS/ExternalXMLServlet?secid=xml812089481&operation=lastpos 

 

Example 2 for a local request

 

http://192.168.1.45:8008/GFS/ExternalXMLServlet?secid=xml812089481&operation=lastpos 

 

 

 

Please note that there is a test site to generate the request. It can be called by calling “geocoding.jsp”

 

e.g.  http://gfs2.sw-management.at/interfaces/Geocoding.jsp 

 

 

 

The encoding of the response is UTF-8.

 

GPS Data Calls 

 

Lastpos

 

Get the last positions of the assets:

 

 

 

 

 

Result:

 

 

 

GPS Data Export

 

The gps data export delivers the rawdata. The last is a number that identifies each gps data record uniquely.

 

IT can be used to load only the records that have not been processed yet.

 

 

 

Result:

 

 

 

Logbook Export 

 

The logbook export generates the completely finished GFS logbook as an XML export.


 

 

 

Result:

 

 

 

 

 

 Geofence Visit Report 

 

Export the visit reports for geofences:

 

 

 

 

 

Result:

 Geofence Activation / Deactivation

  

Result:

 

 

 Geocoding Calls 

 

The geocoding interface enables it to do

 

  •          Reverse Geocoding – get the address from a given lat/lng
  •          Geocoding – get the lat/lng from an address
  •          Bulk Reverse Geocoding – do multiple operations in once call
  •          Bulk Geocoding – do multiple operations in once call
  •          Bulk Reverse Geocoding with geofence creation– do multiple operations in once call and add all items have a certain quality to the system as a geofence
  •          Bulk (Reverse) Geocoding with geofence creation– do multiple operations in once call and add all items have a certain quality to the system as a geofence

 

The geocoding calls also deliver quality information about the calculated address.

Class 

The class returns information about the quality of the response.

Class

Name

Description

0

NOT_CLASSIFIED

No classification is available

1

LOW

The address candidate is of lower quality.

2

HIGH

The address candidate is of average quality.

3

HIGH

The address candidate is a close match to the input

4

EXACT

The address candidate can be considered exact

5

UNIQUE

The address candidate can be considered unique.

If you enter the city name only, the quality will be 5 for high, because the software found it and this is the maximum it can do for you.

If you enter the city and streetname with housenumber and the software returns 5, you have a full hit, of you only have 4 , it might be a smaller spelling problem.

 

 

 

We recommend to use only records with a minimum of 4

 

Detail Level 

 

Level

Name

Description

0

COUNTRY

 

1

STATE

Candidate was found on country level.

2

EXTPOSTCODE

Candidate was found on global postal code level.

3

CITY

Candidate was found on city level.

 

4

CITY2

Candidate was found on city district level.

 

5

POSTCODE

Candidate was found on postal code level.

6

STREET

Candidate was found on street level.

7

HNRSECTION

Candidate was found on house number section level. Note that the address result does not contain a exact housenumber

8

HNRLINK

Candidate was found on house number link level.

9

HNRINTERPOLATED

Candidate was found on house number level, the house number was interpolated.

10

HNREXACT

Candidate was found on house number level, the data contained the exact house number.

11

INTERSECTION

Candidate was found on intersection level, the result data is an intersection.

 

 

 

If you set the house number in street request, 9 is a good result

 

If you don’t set the house number, the maximum you can achieve is 6.

 

 

 

We recommend to use responses with a minimum quality of 9, if the house number is set.

We recommend to use responses with a minimum quality of 6, if the street only is set

 

 

Score

 

The score is a combination of detail level and class and can be stored for further information.

 

Geocoding Address Format

 

Please note that you can use the country field to make the search operation faster and more precise, but you have to use the official 3 character codes (ISO 2166/MA). For more information consider see http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3 

 

 

 

Code 

Country 

Code 

Country 

ABW

Aruba 

LAO

Lao People's Democratic Republic 

AFG

Afghanistan 

LBN

Lebanon 

AGO

Angola 

LBR

Liberia 

AIA

Anguilla 

LBY

Libya 

ALA

Åland Islands 

LCA

Saint Lucia 

ALB

Albania 

LIE

Liechtenstein 

AND

Andorra 

LKA

Sri Lanka 

ARE

United Arab Emirates 

LSO

Lesotho 

ARG

Argentina 

LTU

Lithuania 

ARM

Armenia 

LUX

Luxembourg 

ASM

American Samoa 

LVA

Latvia 

ATA

Antarctica 

MAC

Macao 

ATF

French Southern Territories 

MAF

Saint Martin (French part) 

ATG

Antigua and Barbuda 

MAR

Morocco 

AUS

Australia 

MCO

Monaco 

AUT

Austria 

MDA

Moldova, Republic of 

AZE

Azerbaijan 

MDG

Madagascar 

BDI

Burundi 

MDV

Maldives 

BEL

Belgium 

MEX

Mexico 

BEN

Benin 

MHL

Marshall Islands 

BES

Bonaire, Sint Eustatius and Saba 

MKD

Macedonia, the former Yugoslav Republic of 

BFA

Burkina Faso 

MLI

Mali 

BGD

Bangladesh 

MLT

Malta 

BGR

Bulgaria 

MMR

Myanmar 

BHR

Bahrain 

MNE

Montenegro 

BHS

Bahamas 

MNG

Mongolia 

BIH

Bosnia and Herzegovina 

MNP

Northern Mariana Islands 

BLM

Saint Barthélemy 

MOZ

Mozambique 

BLR

Belarus 

MRT

Mauritania 

BLZ

Belize 

MSR

Montserrat 

BMU

Bermuda 

MTQ

Martinique 

BOL

Bolivia, Plurinational State of 

MUS

Mauritius 

BRA

Brazil 

MWI

Malawi 

BRB

Barbados 

MYS

Malaysia 

BRN

Brunei Darussalam 

MYT

Mayotte 

BTN

Bhutan 

NAM

Namibia 

BVT

Bouvet Island 

NCL

New Caledonia 

BWA

Botswana 

NER

Niger 

CAF

Central African Republic 

NFK

Norfolk Island 

CAN

Canada 

NGA

Nigeria 

CCK

Cocos (Keeling) Islands 

NIC

Nicaragua 

CHE

Switzerland 

NIU

Niue 

CHL

Chile 

NLD

Netherlands 

CHN

China 

NOR

Norway 

CIV

Côte d'Ivoire 

NPL

Nepal 

CMR

Cameroon 

NRU

Nauru 

COD

Congo, the Democratic Republic of the 

NZL

New Zealand 

COG

Congo 

OMN

Oman 

COK

Cook Islands 

PAK

Pakistan 

COL

Colombia 

PAN

Panama 

COM

Comoros 

PCN

Pitcairn 

CPV

Cape Verde 

PER

Peru 

CRI

Costa Rica 

PHL

Philippines 

CUB

Cuba 

PLW

Palau 

CUW

Curaçao 

PNG

Papua New Guinea 

CXR

Christmas Island 

POL

Poland 

CYM

Cayman Islands 

PRI

Puerto Rico 

CYP

Cyprus 

PRK

Korea, Democratic People's Republic of 

CZE

Czech Republic 

PRT

Portugal 

DEU

Germany 

PRY

Paraguay 

DJI

Djibouti 

PSE

Palestinian Territory, Occupied 

DMA

Dominica 

PYF

French Polynesia 

DNK

Denmark 

QAT

Qatar 

DOM

Dominican Republic 

REU

Réunion 

DZA

Algeria 

ROU

Romania 

ECU

Ecuador 

RUS

Russian Federation 

EGY

Egypt 

RWA

Rwanda 

ERI

Eritrea 

SAU

Saudi Arabia 

ESH

Western Sahara 

SDN

Sudan 

ESP

Spain 

SEN

Senegal 

EST

Estonia 

SGP

Singapore 

ETH

Ethiopia 

SGS

South Georgia and the South Sandwich Islands 

FIN

Finland 

SHN

Saint Helena, Ascension and Tristan da Cunha 

FJI

Fiji 

SJM

Svalbard and Jan Mayen 

FLK

Falkland Islands (Malvinas) 

SLB

Solomon Islands 

FRA

France 

SLE

Sierra Leone 

FRO

Faroe Islands 

SLV

El Salvador 

FSM

Micronesia, Federated States of 

SMR

San Marino 

GAB

Gabon 

SOM

Somalia 

GBR

United Kingdom 

SPM

Saint Pierre and Miquelon 

GEO

Georgia 

SRB

Serbia 

GGY

Guernsey 

SSD

South Sudan 

GHA

Ghana 

STP

Sao Tome and Principe 

GIB

Gibraltar 

SUR

Suriname 

GIN

Guinea 

SVK

Slovakia 

GLP

Guadeloupe 

SVN

Slovenia 

GMB

Gambia 

SWE

Sweden 

GNB

Guinea-Bissau 

SWZ

Swaziland 

GNQ

Equatorial Guinea 

SXM

Sint Maarten (Dutch part) 

GRC

Greece 

SYC

Seychelles 

GRD

Grenada 

SYR

Syrian Arab Republic 

GRL

Greenland 

TCA

Turks and Caicos Islands 

GTM

Guatemala 

TCD

Chad 

GUF

French Guiana 

TGO

Togo 

GUM

Guam 

THA

Thailand 

GUY

Guyana 

TJK

Tajikistan 

HKG

Hong Kong 

TKL

Tokelau 

HMD

Heard Island and McDonald Islands 

TKM

Turkmenistan 

HND

Honduras 

TLS

Timor-Leste 

HRV

Croatia 

TON

Tonga 

HTI

Haiti 

TTO

Trinidad and Tobago 

HUN

Hungary 

TUN

Tunisia 

IDN

Indonesia 

TUR

Turkey 

IMN

Isle of Man 

TUV

Tuvalu 

IND

India 

TWN

Taiwan, Province of China 

IOT

British Indian Ocean Territory 

TZA

Tanzania, United Republic of 

IRL

Ireland 

UGA

Uganda 

IRN

Iran, Islamic Republic of 

UKR

Ukraine 

IRQ

Iraq 

UMI

United States Minor Outlying Islands 

ISL

Iceland 

URY

Uruguay 

ISR

Israel 

USA

United States 

ITA

Italy 

UZB

Uzbekistan 

JAM

Jamaica 

VAT

Holy See (Vatican City State) 

JEY

Jersey 

VCT

Saint Vincent and the Grenadines 

JOR

Jordan 

VEN

Venezuela, Bolivarian Republic of 

JPN

Japan 

VGB

Virgin Islands, British 

KAZ

Kazakhstan 

VIR

Virgin Islands, U.S. 

KEN

Kenya 

VNM

Viet Nam 

KGZ

Kyrgyzstan 

VUT

Vanuatu 

KHM

Cambodia 

WLF

Wallis and Futuna 

KIR

Kiribati 

WSM

Samoa 

KNA

Saint Kitts and Nevis 

YEM

Yemen 

KOR

Korea, Republic of 

ZAF

South Africa 

KWT

Kuwait 

ZMB

Zambia 

  

ZWE

Zimbabwe 

 

Data Availability

 

The availability of data depends on the configuration of your account and asset configuration. Some products are licensed with your assets, some on the account.

 

Currently the geocoding data is available for: Europe

 

Currently the reverse - geocoding data is available for: Europe, Middle East

 

 

 

 (Reverse-) Geocoding Parameters

 

The following parameter are available:

 

  •           country
  •           city
  •           postalcode
  •           street
  •         lat
  •          lng

 

If at least the city and street is set, the software will try to calculate the lat and lng in the result, otherwhise if the lat/lng is set, it will try to get the address. If the city and steet and lat/lng is not set it will raise an error.

 

(Reverse-) Geocoding Parameters with Geofence Creation!

Additionally to the address fields the following parameters are used:

Name

Required

Comment

Example

gupdate

Yes

set it to 1 if you also want the geofences to be updated, if it exists already. Set the value to 0, if you don’t want it to be updated.

1 or 0

geofenceName

Yes

Name of the geofence to be created or updated. Please note that are rules for the geofence name for certain but mandatory reasons.

 

Allowed characters are: Space,-,+,(,),@,0..9, a..z,A..Z

 

All other invalid characters will be replaced with: -

Customer Mäier

gmindetail

yes

Set the minimum quality of the address: (See 28.5.2 ). If the quality is too low, the geofence will not be created

9

gminclass

yes

Set the minimum quality of the address: (See 28.5.1 ). If the quality is too low, the geofence will not be created

4

gsizemeter

yes

Set the size of geofence around the center point

50

geofenceAssetID

No

If you set the id, the geofeonce is assigned to the asset only. If the value is null the geofence is assigned to all.

 

Please note that this value is not updated in the case of an existing geofence.

 

geofenceTypeID

yes

Select they type of the geofence.

 

By default the following types are available:

 

0             Standard                              

1             Customer                             

2             Standard-Symbol

3             Standard-no-map

4             Standard-no-map-no list

 

Type 0 uses a rectangle to display the geofence

 

Type 1 uses a rectangle to display the geofence. It could be used later one to filter based on the type.

 

Type 2 can be used to display a container symbol on the map instead of the rectangle.

 

Type 3 is not displayed on the map, because large amount of

Geofences (more than 1000) will make the map display very slow.

 

Type 4 is not displayed in the map and not shown in the rules list view because many geofence records will make the loading too slow.

 

 

 

 http GFS (Reverse-) Geocoding Call 

 

The following http call is calculating the address for a give lat/lng or calculates the lat/lng based on the address.

 

 

 

Result:

 

 

 

http GFS (Reverse-) Geocoding Call & Geofence Update/Creation 

The following call is doing the(reverse-) geocoding operation and creates / updates a geofence with the given name.

Result in the case of an insert

Result in the case of an update

Result in the case of not found

Geofence Creation / Updates & GFS Geocoding Web Call with XML for multiple addresses 

Result:

Result if e.g. updates took place

 

 

.