BatchGeo API

What is the BatchGeo API?

The BatchGeo API allows developers, designers, and even people with nearly no coding experience put a map up with up to 2,500 of geocoded markers with just plain HTML and optionally, JavaScript.

Create a map as easy as:

1. Add this script tag to your HTML document (usually right before </body>)

<script src="http://batchgeo.com/api/js/"></script>

2. Create an element to put the map inside and give it an ID prefixed with batchgeo-map-

<div id="batchgeo-map-1"></div>

3. Make a list of addresses and give it an id prefixed with batchgeo-data- and match the name ID's name with the previous step.

<ul id="batchgeo-data-1">
  <li>Here's where the Trailblazers Play!<br /><address>Rose Quarter, Portland, OR</address></li>
  <li>Nice restaraunt over here!<br /><address>8 NW 6th Avenue Portland OR</address></li>
  <li>Visit our favorite Park here!<br /><address>3862 Southeast Hawthorne Boulevard, Portland, OR</address></li>
</ul>

That's it! You just made a map with 3 clickable markers:

• Here's where the Trailblazers Play!
  
  Rose Quarter, Portland, OR
• Nice restaraunt over here!
  
  8 NW 6th Avenue Portland OR
• Visit our favorite Park here!
  
  3862 Southeast Hawthorne Boulevard, Portland, OR

Why Use The BatchGeo API

All the reasons for using the BatchGeo API might not be immediately apparent, but there are numerous useful and time saving reasons.

Web Designer or Site Owner

Most commonly it's great to list out a bunch of business addresses. For example, let's say you or a client has a website for a chain of local restaurants. You can use the BatchGeo API to generate a map for you based on a simple <ul> list you made with your WYSIWYG editor of all the restaurant locations.

Blogger

Another common use is for bloggers making listings of all the concerts happening this weekend. That can easily make a list in their WYSIWYG editor and include some text with the locations with the band name and start / end time of the shows.

App Developer

App developers will find this as an awesome tool for making maps for their mobile or HTML5 apps. Even if you're a developer you might not wanna learn the massive Google Maps API just to do some minor plotting.

What the BatchGeo API Is and Isn't

The BatchGeo API, in short, is a JavaScript library for giving addresses and major landmarks (like business names, park names, etc.) and generate a map on the fly via the Google Maps API and caches the results on our server so load times are instant all subsequent requests. The library lets you create maps with lots of markers and lets you set data for markers, but this isn't a full on JavaScript library for mapping nor is it trying to be.

Although the API is heavily inspired by jQuery, it is not a jQuery plugin. Instead of something in the prototype JS OOP format, we went with the jQuery type of JS OOP. This means, instead of a var map = new batchgeo.map({selector:'#mymap'}); style (something like Google Maps) it's much simpler and jQuery like with this syntax: batchgeo('#mymap');.

Also, the API doesn't allow any real GIS features like creating polygons or creating your own map layers (although it has some predefined layers such as traffic, bicycling, and others). It also doesn't do anything with shape files. It's meant for creating basic maps easily with just HTML or some JS. If you're looking to do more heavy mapping like this check out some of these projects:

• Polymaps - Polymaps provides speedy display of multi-zoom datasets over maps, and supports a variety of visual presentations for tiled vector data
• Google Maps jQuery Plugin - The Google Maps jQuery Plugin lets you simply embed Google Maps using The Google Maps JavaScript API in your web pages.
• Leaflet - Leaflet is a modern, lightweight BSD-licensed JavaScript library for making tile-based interactive maps for both desktop and mobile web browsers

Feature List

Here are just some of the features available in the BatchGeo API

• Create maps without ever touching a line of JavaScript.
• Include your Adsense ID and make money off your maps.
• Create a dynamically generated map with a single line of JavaScript.
• Easily change the HTML and contents of the info windows.
• Completely JavaScript library independent (use it with jQuery, MooTools, or any other library).
• Accepts any CSS3 selector when selecting elements.
• Supports the following layers:
  • bicycling
  • traffic
• Supports the following map types:
  • satellite
  • terrain
  • hyrid
  • roadmap
• Easily add your own custom marker images.
• Hide or show map controls.
• Marker animation can be turned on or off.

And more! Is it missing a feature? Add your request to the GitHub project page's bug and feature tracker.

Project Status and Roadmap

Project Status

Currently we're in the public beta stage. We currently support Firefox 3.5+, Chrome 9+, and IE7+ and probably more browsers that we just haven't tested. The map is completely useable and it's stable.

Roadmap

We're constantly trying to improve our API and make it even more powerful, but keep just as quick and easy as it is currently. Here are some features we're looking into (please note that none of these features are set in stone.):

• Programmatically Add/Remove Markers Via the JS API*
• Bookmarkable URLs
• Locator box for finding closest location*
• Support for making maps with directions/routes

*these are highly requested features we are actively working on

Check out the GitHub project page's issue and bug tracker if you want to submit a feature request.

License

Copyright (c) 2011 BatchGeo

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

JavaScript API

Quick Start

While BatchGeo allows you to create maps just with HTML, sometimes you need a little more control over the map such as when it's invoked for things such as AJAX applications for example. This is when the JS API comes in handy. This guide will get you started quickly and you can look into each method of the JS API separately under the "JavaScript API" section.

The first step is to include the JavaScript tag just like you would for the HTML API like this:

<script src="http://batchgeo.com/api/js"></script>

Next, we need to create an HTML element for the map to be generated in and give it an ID like so:

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

Now we need to choose how we want to give the data to BatchGeo. The JavaScript API supports a few methods of doing so. You can either give it a JSON string, JS object, or a selector to a <ul> or <ol>. For the sake of example we'll just use a JS object. For more infomation on these different formats see the .source() API page.

var addr = [
  {
    address:'Rose Quarter, Portland, OR',
    info:'The Rose Quarter. This place is <strong>huge</strong>.'
  },
  {
    address:'8 NW 6th Avenue Portland OR',
    info:'This place is smaller, but has an upper deck which is cool.'
  },
  {
    address:'3862 Southeast Hawthorne Boulevard, Portland, OR',
    info:'One of my favorite venues. They always have the best indie and punk bands here.'
  }
];

Finally we pull all of this together. BatchGeo has nothing to do with jQuery, but does use the Sizzle selector engine, so you can select an element just like jQuery. Also, because the BatchGeo API loads numerous files and does all kinds of magic behind the scenes, you need to place your scripts in a .ready() method. Here's an example of putting it all together:

batchgeo.ready(function(){
  batchgeo('#my-map').source(addr).map();
});

JavaScript API

You can learn more about the specific BatchGeo methods here.

• batchgeo()
• .source()
• .options()
• .map()

batchgeo()

Examples:

Example of batchgeo

batchgeo.ready(function(){
  //Put your batchgeo calls inside of here
});

Example of batchgeo(selector)

batchgeo.ready(function(){
  batchgeo('#my-map').source([{address:'123 some place, some city, CA'}]).map();
});

.source()

Examples:

Example of source(selector)

The source(selector) method allows you to grab a <ul> or <ol> containing <li>s with <address> tags inside that have the addresses you want to map. Any additional HTML will be used as the description.

batchgeo.ready(function(){
  batchgeo('#my-map').source('.my-data').map();
});

The HTML for this would look something like

<ul class="my-data">
  <li>
    <address>123 some street, some place, CA</address>
  </li>
  <li>
    <address>456 other street, new place, CA</address>
  </li>
</ul>

Example of source(JSON)

The JSON parameter allows you to give it a string of JSON and it'll use that to map. In your JSON use the keys address to mark an address and info to mark the info for the marker which can include HTML.

Note: data must be in an array.

batchgeo.ready(function(){
  batchgeo('#my-map').source([
    {
      "address":"123 some street, some place, CA",
      "info":"Just some place"
    },
    {
      "address":"456 other street, new place, CA",
      "info":"<strong>Another</strong> one of those places."
    }
  ]).map();
});

Example of source(object)

The object parameter allows you to give it a JavaScript object and it'll use that to map. In your JavaScript object use the keys address to mark an address and info to mark the info for the marker which can include HTML.

Note: data must be in an array.

batchgeo.ready(function(){
  batchgeo('#my-map').source([
    {
      address:"123 some street, some place, CA",
      info:"Just some place"
    },
    {
      address:"456 other street, new place, CA",
      info:"<strong>Another</strong> one of those places."
    }
  ]).map();
});

.options()

Examples:

Example of options(object)

The object parameter in the options method provide hooks into changing all sorta of things on the map from it's dimensions to different layers such as traffic to different map types to even changing the marker images. For more info on all of the options go to the Option Reference page.

batchgeo.ready(function(){
  batchgeo('#my-map').source('#my-data').options({width:'500px',traffic:true}).map();
});

.map()

Examples:

Example of map(string)

The string parameter is optional and can be either create or remove. By default, as in all of these examples, .map() defaults to create.

batchgeo.ready(function(){
  batchgeo('#my-map').source('#my-data').map();
});

HTML API

Quick Start

Create a map as easy as:

1. Add this script tag to your HTML document (usually right before </body>)

<script src="http://batchgeo.com/api/js"></script>

2. Create an element to put the map inside and give it an ID prefixed with batchgeo-map-

<div id="batchgeo-map-2"></div>

3. Make a list of addresses and give it an id prefixed with batchgeo-data- and match the name ID's name with the previous step.

<ul id="batchgeo-data-2">
  <li><address>Rose Quarter, Portland, OR</address></li>
  <li><address>8 NW 6th Avenue Portland OR</address></li>
  <li><address>3862 Southeast Hawthorne Boulevard, Portland, OR</address></li>
</ul>

That's it! You just made a map with 3 clickable markers:

• Rose Quarter, Portland, OR
• 8 NW 6th Avenue Portland OR
• 3862 Southeast Hawthorne Boulevard, Portland, OR

Understanding BatchGeo Mapping

The power of BatchGeo's HTML API is that it's so simple. There are only really a few things you have to know about BatchGeo's API to get it to work.

First, and most obvious, you need to link to the API like this:

<script src="http://batchgeo.com/api/js"></script>

Next you should understand how BatchGeo reads the HTML as of now. It looks for 3 things:

1. ID's that start with either #batchgeo-map- and #batchgeo-data-.
2. <address> tags.
3. The data HTML5 attributes that start with data-batchgeo-.

The ID #batchgeo-map-anything tells BatchGeo that "this" is where you want to put the map when it's generated. This can be any tag, including a made up tag if you wanted. The #batchgeo-data-anything ID tells BatchGeo that "this" contains the map data which would be the addresses and HTML you want to put in the popup bubbles. The word "anything" in these examples is the name of the map and it's how BatchGeo knows "this" map is related to "this" dataset.

The #batchgeo-data- currently has to be a <ol> or <ul> and it looks for <li>s inside that contain <address>s. These <address>s are used as the address' to map out. Any additional HTML inside is used for the bubble.

Lastly there are the HTML5 data attributes that you put on the #batchgeo-map-anything element. You'd do this like <div id="batchge-map-anything" data-batchgeo-map-type="hybrid">. For all these options you can go to the Option Reference page.

Option Reference

This is a quick reference table on each of the options, what they do, and the JavaScript and HTML names of them. They also each include an example of what happens when you modify them.