It's now time to start using the API. Follow the instructions as mentioned, open a new Notebook in the Jupyter Notebook application where you can access the API. Type and run the following code. We'll start by importing the API so that we can use its modules, functions, and classes:

In:   import arcgis
In:   from arcgis.gis import GIS

The second line of the code can be broken down as follows—arcgis.gis refers to a submodule (gis) in the arcgis module. What's being imported (GIS), is a GIS object that includes a map widget for displaying geographic locations, visualizing GIS content, as well as the analysis results. Next, we'll create a GIS object by assigning it to a variable with the same name, but spelled in lowercase:

In:   gis = GIS()

This is an example of an anonymous login as we don't pass in any login details between the parentheses of GIS(). Now we'll use the map widget by creating a map object and assigning it to a variable that can then be queried to bring up the widget in the Notebook:

In:   map1 = gis.map('San Francisco')
      map1

Note that you have to repeat and run the variable name on a separate, new line to have a map displayed. A map window will be opened in your Jupyter Notebook application showing a 2D color map of the city of San Francisco:

You can adjust the zoom level of the map through the zoom property and passing in an integer:

In:   map1.zoom = 5

A map display without a zoom-level value gives you a default zoom value of 2. A larger value will give you a smaller area showing more details, using a larger scale. This map is one of the several basemaps that ArcGIS Online offers as a backdrop for mapping data. We can query which type of basemap we're displaying currently:

In:   map1.basemap

Out: 'topo'

You might want to know how to access all of the object properties. This can be done by typing the object name, followed by a dot and pressing Tab. Then, a window with a drop-down list containing all available properties will be displayed:

We can see the basemap property being listed in the previously mentioned screenshot. For more information on a given property, select the property of your choice followed by a question mark. Then, an information window will open at the bottom of your screen displaying more information:

In:   map1.basemaps?

The basemaps property can also be queried directly and returns a list object including new lines for each value:

In:   map1.basemaps

Out: ['dark-gray',
    'dark-gray-vector',
    'gray', ...

We can use the information from this window by changing our basemap, by passing in one of the available options in the basemap property (note the singular) as follows:

In: map1.basemap = 'satellite'
    map1

We can see that our basemap now shows a satellite image of San Francisco:

Next, we'll query the coordinate reference system (CRS) of the map that is displayed in our map widget. This information can be queried with the extent property, which also shows the four coordinates of our extent:

In: map1.extent

Out: {'spatialReference': {'latestWkid': 3857, 'wkid': 102100},
 'type': 'extent',
 'xmax': -13505086.994526163,
 'xmin': -13658266.799209714,
 'ymax': 4578600.169423444,
 'ymin': 4517450.546795281}

Let's have a look at the output. Our basemap is an example of a web map, which comes in JavaScript Object Notation (JSON) format for sharing 2D maps. Web maps are an example of an Esri specification that allows different applications, APIs, and SDKs to create, edit, and display maps. These web maps can be used for different Esri applications, such as ArcGIS Online in this particular example. The web map specification is in JSON, which is indeed the case with our output by looking at how it is structured using brackets and using key-value pairs.

Back to the spatial reference, this information is stored in the spatialReference object, located at the top-level of the web map JSON hierarchy. In our example, we can see the spatial reference being set as latestWKid: 3857 and wkid: 102100. Consulting Esri's online web map specification available at http://developers.arcgis.com, we can see that both refer to a Web Mercator projection, the de facto standard for web mapping applications and used by most major online map providers.

This concludes our first hands-on exercise of the API in which we learned how to import the API, create a map object, display information on properties of an object, and use the map widget. In our next exercise, we'll start working with content from ArcGIS Online and add it to our map widget. We'll use a personalized account, which enables us to create our own web maps and host them online. Before we can do this, you'll need to create a personalized ArcGIS Online account, which we'll cover next.