# Maps

The Geodir Maps API allows you to customize maps with your own content and images for display on web pages and mobile devices. The Geodir Maps API presents a basic map (roadmap) that you can modify using layers and styles, controls and events, and various services and libraries.

# Important

This documentation is designed for people familiar with programming JavaScript (opens new window) and the concepts of object-oriented programming. You should also be familiar with Geodir Maps (opens new window) from the user's point of view. There are many JavaScript tutorials (opens new window) available on the Web.

This concept documentation is designed to allow you to quickly start exploring and developing applications with the Geodir Maps API. You can also check out the Maps JavaScript API Reference (opens new window).

# Maps API Request Format

The easiest way to start learning about the Geodir Maps API is to see a simple example. The following example shows a centered map:

<!DOCTYPE html>
<html>
	<head>
		<title>Display a map</title>

		<meta charset="utf-8" />		
		<meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no" />
		
		<link rel="stylesheet" href="https://unpkg.com/maplibre-gl@1.14.0-rc.1/dist/maplibre-gl.css"/>
		<script src="https://unpkg.com/maplibre-gl@1.14.0-rc.1/dist/maplibre-gl.js"></script>		
	</head>

	<body>
		<div id="map"></div>

		<style>
			body {
			    margin: 0;
			    padding: 0;
			}

			#map {
			    position: absolute;
			    top: 0;
			    bottom: 0;
			    width: 100%;
			}
		</style>

		<script>
			var map = new maplibregl.Map({
			    container: 'map', // container id
			    style: 'https://apis.geodir.co/maptype/geodir-lightv1?key=YOUR_KEY', // style URL
			    center: [-77.05, -12.05], // initial position [lng, lat]
			    zoom: 13 // initial zoom
			});
		</script>
	</body>
</html>

Even in this simple example, there are a few things to keep in mind:

We declare the application as HTML5 using the <!DOCTYPE html>.
We create a div element called "map" to contain the map.
We load the Maps JavaScript API using a script tag.

These steps are explained below.

# Declare your Application as HTML5

We recommend that you declare a true DOCTYPE within your web application. Within the examples here, we have declared our applications as HTML5 using the plain HTML5 DOCTYPE as shown below:

<! DOCTYPE html>

Most of the current browsers will display the content declared with this DOCTYPE in "standard mode", which means that your application should be more compatible with all browsers. The DOCTYPE is also designed to gracefully degrade; browsers that don't understand it will ignore it and use "quirky mode" to display its content.

Note that some CSS that work in quirks mode are not valid in standard mode. Specifically, all percentage-based sizes must inherit from elements in the parent block, and if any of those ancestors don't specify a size, they are assumed to be 0x0 pixels in size. For that reason, we include the following statement <style>:

<style>
  	body {
		margin: 0;
		padding: 0;
	}

	#map {
		position: absolute;
		top: 0;
		bottom: 0;
		width: 100%;
	}
</style>

This CSS declaration indicates that the map container <div> (with id map) should occupy 100% of the HTML body. Note that we must also specifically declare those percentages for <body>.

# Loading the Maps JavaScript API

The Geodir Maps API is loaded using a <script> tag, which can be added online in your HTML file or dynamically using a separate JavaScript file. We recommend that you review both approaches and choose the one that is most appropriate for the way your project code is structured.

# HTTPS or HTTP

We believe that security on the web is very important and we recommend using HTTPS whenever possible. As part of our efforts to make the web more secure, we have made all of the Geodir Maps APIs available over HTTPS. Using HTTPS encryption makes your site more secure and more resistant to spying or tampering.

We recommend loading the Geodir Maps API over HTTPS with the tag <script> provided above.

If necessary, you can load the Geodir Maps API via HTTP by requesting http://apis.geodir.co.

# DOM Elements Map

<div id="map"></div>

In order for the map to be displayed on a web page, we must reserve a place for it. We usually do this by creating a named div element and getting a reference to this element in the browser's document object model (DOM).

In the example above, we used CSS to set the height of the map div to "100%". This will expand to accommodate the size of mobile devices. You may need to adjust the width and height values based on your screen size and browser padding. Note that divs generally take their width from their container element, and empty divs are generally 0 in height. For this reason, you should always set a height in the <div> explicitly.

# Map Options

There are two mandatory options for each map: center and zoom.

var map = new maplibregl.Map({
    container: 'map', // container id
    style: 'https://apis.geodir.co/maptype/geodir-lightv1?key=YOUR_KEY', // style URL
    center: [-77.05, -12.05], // initial position [lng, lat]
    zoom: 13 // initial zoom
});

# Zoom Levels

The initial resolution for displaying the map is set by the zoom property, where zoom 0 corresponds to a map of the Earth completely out of the way, and larger zoom levels zoom in at a higher resolution. Specify the zoom level as a whole number.

zoom: 8

Offering a map of the entire Earth as a single image would require a huge map or a small map with very low resolution. As a result, Geodir Maps map images and the Maps JavaScript API are divided into map "tiles" and "zoom levels." At low zoom levels, a small set of map tiles covers a wide area; at higher zoom levels, the tiles have a higher resolution and cover a smaller area. The following list shows the approximate level of detail you can expect to see at each zoom level:

1: World
5: Continent
10: City
15: Streets
20: Buildings

Obtain your api key →