Outline

Integrator API allows you to utilize all functions avalable at UMapper.com directly from your own website. This is done by relying on XML-RPC protocol. If you are new to RPC - start with our tutorial.

In a nutshell, RPC (or Remote Procedure Calls, hence the name RPC) allows you to trigger the procedures located on UMapper.com directly from your PHP application. It is a de facto standard in IT industry, so costs of integration are low.

Theory of operation

General operation sequence when using API would be as following:

1. Connect to UMapper and obtain session key (see api.connect()). In order to connect you would need to provide integrator's username, password and API key.
2. Once connected, use obtained session token along with your API key to invoke any of remote methods described below.
3. Once executed method returns result, on error exceptions are thrown - so always check your results for exceptions (see test() method) to make sure that your call is successful.

To get you started quickly we have prepared an easy to follow tutorial describing the remote method invocation.

Couple of notes before you start

1. Arguably the most easy way to utilize the XML-RPC protocol is to use Zend Framework - it has a very rich library of classes. For those who doesn't want to use full Zend Framework, we prepared the Integrator Toolkit. Toolkit contains only those ZF classes that are required to successfully run the XML-RPC client.

2. All examples are written in PHP5 and use Zend Framework. Thus, in order to be able to run the samples, you either have to install Zend Framework, or use Integrator Toolkit.

3. IMPORTANT! All XML-RPC requests should be forwarded to
   

   http://www.umapper.com/services/xmlrpc/integrator/

4. You would need to provide valid credentials in order to use Integrator API. Sandbox credentials:
   

   1 2 3

   Client username:    UMapperTester Client password:    password API Key:            test

5. All new accounts and maps, added via sandbox account, would be purged once a day at 00:00 GMT

Test UMapper connection

In order to check whether your application is able to "talk" to UMapper servers, we have implemented test() method:

Definition: Test function to check whether server responds or not.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

Output:

1

If everything goes all right, then you should get the "RPC Call Sucessfull!" message in your browser. If you wanted to test how exceptions are thrown you shuold pass additional parameter to $client->call():

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

UMapper server responds with an exception, which may have the following dump:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Connect to UMapper

The very first thing you'd want to do when using the API is to connect to UMapper system. This is accomplished via api.connect() method. Here is the syntax:

Def: You feed this function your credentials and it returns the valid session token you would be using for any successive call to Integrator API.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

Output:

1

As you can see, we do not have to worry about XML being transfered back and forth between your site and UMapper - everything is abstraced in Zend_XmlRpc_Client class. The resultant string (which we saved in $response variable) is your session token, and could be used for successive calls right away.

Create new user account

Integrator API allows you to create user accounts that would be stored within UMapper system, and could be used for map assignment.

Definition: Adds new user account to specified user system. Returns new accounts DB primary key, if call succeed.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

Output (newly created account id):

1

Retrieve user account details

When you need to re-check user account's details you should resort to api.getUser():

Definition: Returns user data as associative array.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

Output:

1
2
3
4
5
6
7
8
9
10
11

Retrieve user ID

Sometimes, you have username and want to retrieve account ID for that username, api.getUserId() is exactly for that:

Definition: Returns user ID from username.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Output:

1

Edit existent user account

When you need to update specific user account, use api.editUser():

Definition: Edits user account for a given sub-system, number of rows updated returned (if operation succeeds, obviously equals to one - 1).

Please note that $password, $fname, $lname, and $email are optional parameters.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

Output:

1
2
3
4
5
6
7
8
9
10
11
12
13

Delete user account

In order to remove user account (registered with your website) from UMapper servers use api.deleteUser():

Definition: Removes user account from database, number of rows deleted returned (should be equal to 1).

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

Output:

1

Create new map

In order to use the UMapper Map Editor, you have to create map record in our database and assign it to one of your users. All this could be done with api.creatMap() method:

Definition: Creates map (populates map meta-data), Map ID of newly created map record (or zero on error) is returned.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

Output:

1

Get map meta-data

Once map record is created you can retrieve its content by using api.getMapMeta() method:

Definition: Retrieves the map meta-data as associative array.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

Output:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

Retrive map URI

Map source data is stored in XML format (more specifically in highly extensible KML), an in order to load some map into UMapper Map Viewer or UMapper Map Editor, you would need an URI to the KML source file - api.getMapUri() was designed for such needs:

Definition: Returns the path of map file (currently in KML format).

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

Output:

1

Generally, it is safe to assume that map URI would be generated as following:

Still, the function would always return correct source path, so it is advised for forward-compatibility.

Update map meta-data

Once your map is created there may be situations when you need to update, say, map title or description - map meta data. This is done with api.updateMapMeta():

Definition: Updates map's meta-data. Number of rows updated is returned (generally 1, if operation succeeds).

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

Output:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Update map data (XML source)

Map source data is stored in XML format (more specifically in highly extensible KML), and method api.updateMapData is used to associate some KML data with certain map:

Definition: Updates map's KML data. Number of rows updated is returned (generally 1, if operation succeeds).

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

Contents of myMap.xml file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Output:

1

Delete Map

Believe it or not, but sometimes maps should be deleted, not surprisingly api.deleteMap() does exactly that:

Definition: Deletes map and corresponding resources, number of rows (generally 1) is returned.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

Output:

1

Return list of user maps

In order to retrieve the list of maps associated with user account, use api.getMaps():

Definition: Returns array of maps, if any, registered with a given user account.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

Output:

1
2
3
4
5
6
7