Outline

Simple Maps API, makes it really simple to acceess your user account 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 maps.connect()). In order to connect you would need to provide UMapper username, password and API key (obtain it by accessing your UMapper account).
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/

4. You would need to provide valid credentials in order to use Simple Maps API. Sign up for completely FREE UMapper account, in order to obtain your connection details.

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 maps.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 Simple Maps 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.

Connect to UMapper using API key only

When you need to connect to UMapper, but do not want to provide your username and password, you can do it by providing just your API key. Here's how:

Def: You feed this function your API key and it returns the valid session token you would be using for any successive call to Simple Maps 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

Output:

1

Verify UMapper API Key

In order to check whether your API key is valid or not, use maps.verifyApiKey() method:

Def: Checks whether API key is valid or not, boolean true is returned if key is valid, false if otherwiser.

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

Output:

1

Create new map

In order to use the UMapper Map Editor, you have to create map record in our database. Use maps.creatMap() method to accomplish this:

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 maps.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 - maps.getMap() 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 maps.saveMapMeta():

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 maps.saveMap is used to associate some KML data with certain map:

Definition: Updates map's KML data. Boolean true is returned if operation succeeds, false otherwise.

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

Sometimes maps should be deleted, not surprisingly maps.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 your account, use maps.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
8
9
10
11
12