ThinkGeo Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Map Suite WebAPI Getting Started ======

===== Video Overview =====
{{youtube>0ykmSY6ChHk?large |Web API Getting Started Sample}}

<div newline/>
<div download_viewsource_buttons>
[[Source_Code_WebAPIEditionSample_GettingStarted.zip|View Source]]
{{filehistory:WebAPIEditionSample_GettingStarted_CS_20150417.zip|C# Download}}
[[http://samples.thinkgeo.com/WebApiEdition/SampleTemplates/GetStartedWithMap/leaflet/|leaflet sample]]
[[http://samples.thinkgeo.com/WebApiEdition/SampleTemplates/GetStartedWithMap/openlayers/|openlayers sample]]
</div>


===== Introduction =====
The Map Suite WebAPI is a server-side mapping component for creating your own customizable web mapping application. It allows you to render your map tiles, query and manage data on the server side, and perform a variety of geometric function calculations (such as calculating the area of a user-drawn rectangle on the map).
You can easily build up REST-based web services with the WebAPI in your web applications, or any other applications that consume REST-based services. Build any web REST APIs to meet your exact app requirements. You can also use the JavaScript mapping library of your choice, such as Leaflet or OpenLayers. You’ll have full control over the client-side JavaScript so you can build applications with responsive design that's optimized for a variety of mobile devices.

The JavaScript client dynamically request maps from the server side by making HTTP requests to GetTile REST Methods on the server, each of these individual tiles or “cells” make up a gridded or mosaicked version the entire map. The tiles are rendered to the client in "Slippy Map" X, Y, and Z interfaces that enable responsive panning and zooming that you come to expect in modern applications.

=====Getting Started with your First Map=====
This section provides an overview of how to build your first application, including sample source code. 


====Set Up a Web Page====
To get started, you'll need to create a web page that will house your map application, and reference the JavaScript library of your choice (Leaflet, OpenLayers, etc.) in the page’s header. Include a div element that will serve as the container for your map, and make sure it has a defined height. For details, see the [[Map_Suite_WebAPI_Edition_Quick_Start_Guide|Quick Start Guide]].

====Add a Basemap====
A basemap is just what it sounds like - a base that provides context for your own maps and data, which will be rendered on top of it. The World Map Kit comes with its own default basemap. Simply reference the cloud-based World Map Kit Online in your page's code to connect to it and have map images delivered back. However, you can also choose to use Google, Bing, or another basemap if you prefer.

===Set the Initial Extent of the Basemap===
You may want to set the map’s initial extent. This is the geographical area that displays when a user first opens the application. You can easily do this by programmatically setting a bounding box around the area in one of three ways: 
\\
1. Code in the geographic coordinates (latitude and longitude) of the upper left point and lower right point delineating the area you want to use.
\\
2. Automatically pull coordinates from the location information the user’s device or browser provides.
\\
3. Use the extent of an existing feature or set of features. 
\\

If you prefer, you can also build your own basemap with the WebAPI Edition.

====Understanding Scale====
Zoom levels correspond to preset scales. Scale is a ratio between the distance represented on the map and the corresponding distance on the ground, when measured in the same units. For example, if you view a map at a scale of 1:100,000, one inch on the screen is equal to 100,000 inches on the ground. A map is larger in scale when the features appear “large” or more detailed, and less area is covered (for example, a map of Central Park). A map is smaller in scale when features appear “small”, but more area is covered (a map of New York City or New York State). 

WebAPI Edition comes with 20 preset zoom levels, which can be customized to correspond with your own desired scales.

{{webapiedition:NY-large-small.png|Maps of Central Park (larger-scale) and New York City (smaller-scale). Note the scale, zoom level, latitude and longitude. These appear in the lower left corner of the screen.}}

====Understanding Coordinates====
Your application will need to convert between world and screen coordinates so it knows how to display or center a chosen geographical area in the correct location on the screen.

===World Coordinates===
By default, the WebAPI uses latitude and longitude coordinates to refer to positions on the earth. Lines of latitude run horizontally east and west and always remain parallel to each other. They originate at the equator and expand away from it, toward the poles. Lines of longitude run north and south and converge at the poles. They originate at the prime meridian, which passes through Greenwich, England. The intersection of the equator and the prime meridian is the origin of the latitude/longitude coordinate system (zero degrees latitude and longitude).

===Screen Coordinates===
Screen coordinates are used to specify locations on a device’s screen using x,y coordinate pairs. Coordinates are based on pixel locations. The origin (0,0) is the upper left corner of the display screen, with the x-coordinate increasing along with the number of pixels to the right, and the y-coordinate increasing down.

====Interacting with the Map====
Standard map functionality is automatically included. Users can use the pan tool to drag the screen to another geographical extent. They can also zoom into a larger scale to see a smaller area in greater detail, or zoom in out to view a larger area in less detail. Menu buttons allow the user to switch back to the previous extent.
\\ \\
Users can work with this interactive map through various tools and features. Some features are enabled through click events. You can set up a variety of click events to add functionality to your map. For example, a right-click menu might include options to display the latitude and longitude coordinates of the chosen point, or to center the map at that point. Click events can also generate popups with other information or custom messages. With full control over the client-side JavaScript, you're even free to create your own click events to perform virtually any task on the server side.

\\

{{webapiedition:right-click-events.png|A few basic right-click events.}}

====Ready to get started?====
Now that you're up on the basics of using the Map Suite WebAPI, you're ready to start implementing your own application! You'll find step-by-step instructions in the 
[[Map_Suite_WebAPI_Edition_Quick_Start_Guide|Quick Start Guide]] to help get you on your way.
User Tools

Site Tools

Page Tools
