Translation

AMap’s documentation is in Chinese and most links here make reference to it. If you happen not to know Chinese, it is convenient to set your browser to auto-translate. This will help a little or a lot depending on the website/page structure. One can also copy/paste text to Google translate.

Installation

Install amapro from CRAN with

install.packages("amapro")
Install amapro from Github with
remotes::install_github("helgasoft/amapro")
Then run the following R commands
library(amapro); am.init()
A pop-up dialog will ask for an API key (shows once, will not be repeated).
API key is obtained through registration, expecting you to provide a Chinese phone number for the SMS verification code.
How to get an API key if you reside out of China?

• ask a friend from China to help, or hire a local freelancer
• search the web for a shared key
• use a temporary Chinese phone number from sites like sms24, turtle-sms, etc. However most are probably blacklisted as the registration page shows them as already registered.
• select temporarily the ‘demo’ option, without guarantee to work in the long run

Shiny Demo

Interactive, hands-on showcase of many library features. Activate with the following command:
library(amapro); demo(am.shiny)

API links

amapro is based on version 2.0 of AMap (JSAPI v2.0). “API” auto-translates as “Reference book” in web menus.

Commands

Controlling map and items is done by sending AMap commands to them.
Example: am.cmd('setAngle', 'carIcon', -90)
amapro uses native AMap commands and introduces these additional:

• set - create new item
  • with name: add new global JS object outside the map
    am.cmd('set', 'VectorLayer', name='e$layer1')
  • without name: add new item to map
    am.cmd('set', 'e$marker1', position= c(116.478, 39.998))
• addTo - append one existing JS object to another by name
  am.cmd('addTo', 'e$layer1', 'e$marker1')
• var - set a JavaScript variable
  am.cmd('var', 'e$myOpacity', 0.8)
• code - execute JavaScript code
  am.cmd('code', 'alert("I am JS");')

AMap commands starting with get return data from the map or related objects.
Put the data in a Shiny input variable by setting its name in parameter r.
Example: am.cmd('getCenter', 'map', r='inShiny1')
Above command will update input$inShiny1 with the Lng/Lat coordinates of the map center.

Events

Events could be defined for map and items. All types of instances use on/off methods to bind and remove events.
Events are set in attribute on(or off) as a list of lists. Each event is a separate list with event name in e, a JS function f and optionally a query q.
Example:

am.init(center= c(116.475, 39.997), zoom= 17,
        on= list(list(e= 'complete', 
                      f= "function() {alert('loaded!');}")) )

on/off events without name are ignored, except for the map itself (as above example).
Function Shiny.setInputValue() can be used in JavaScript to send data back to Shiny.

Limitations

• only one map is created by am.init per session. It is a JS global called ‘m$jmap’.
• AMap command addTo is overwritten by amapro and cannot be used.
• AMap plugins supported are ControlBar, Scale, ToolBar, MoveAnimation, MouseTool, HeatMap, GeoJSON, ElasticMarker.
• Loca supported items are GeoJSONSource, PolygonLayer, ScatterLayer, LinkLayer, PulseLinkLayer. Loca events are not supported yet.
• most built-in AMap tile layers (Satellite, Traffic, Roads) are limited to China only. However, with command am.item(‘TileLayer’), one can use any Leaflet provider for worldwide coverage.
• AMap built-in map layers are GCJ-02 coded and coordinates collected on them will display incorrectly in Leaflet or other WGS-84 based maps, and vice-versa. They need to be converted. Conversion is available through function convertFrom.
• AMap ecosystem is vast, some unsupported features include: ‘BesizerCurve’, ‘MarkerCluster’, ‘HawkEye’, IndoorMap, CustomLayer, ‘GLCustomLayer’, ‘DistrictLayer’, ‘LayerGroup’, all editors like ‘PolygonEditor’,‘Webservice’, ‘Search(AMap.Autocomplete, AMap.PlaceSearch)’, ‘Geocoding(AMap.Geocoder)’, Route planning, other services(weather, districts, etc.), positioning, utilities.

Tips

• all named objects created in JS are global variables (window.name). Good practice is to use a name prefix (m$) to avoid overwriting accidentally external variables.

• API attributes could be set to a JS function instead of a value. Function is defined as a string starting with word “function”.

• usually WMS/WMTS tiles come from external servers and may present a CORS problem - browser refusal to load. One can install a small extension in Chrome or Firefox to fix this problem manually inside the browser.

• AMap has several predefined Map styles. Could be set in map options with mapStyle.

• amapro silent errors are collected in the browser Console. Press key F12 to open the dev.environment, then open tab “Console” to view them.

• Chrome/Firefox extensions may interfere with map presentation (like ‘uBlock’)