Static Maps API

Parameters

Parameters can be sent in either the query string or in the POST body.

• zoom - optional - Set the zoom level for the map. If not specified, a zoom level will be chosen that contains all markers on the map.
• maxzoom - optional - When a zoom level is chosen automatically, this sets an upper limit on the zoom level that will be chosen. Useful if you know your basemaps don't have imagery past a certain zoom level.
• width - default 300 - Width in pixels of the final image
• height - default 300 - Height in pixels of the final image
• basemap - default "osm" - Select the basemap
  • osm - Open Street Map
  • streets - Default Esri street basemap
  • satellite - Esri's satellite basemap
  • hybrid - Satellite basemap with labels
  • topo - Esri topographic map
  • gray - Esri gray canvas with labels
  • gray-background - Esri gray canvas without labels
  • oceans - Esri ocean basemap
  • national-geographic - National Geographic basemap
  • otm - OpenTopoMap
  • stamen-toner - Stamen Toner black and white map with labels
  • stamen-toner-background - Stamen Toner map without labels
  • stamen-toner-lite - Stamen Toner Light with labels
  • stamen-terrain - Stamen Terrain with labels
  • stamen-terrain-background - Stamen Terrain without labels
  • stamen-watercolor - Stamen Watercolor
  • carto-light - Carto Free usage for up to 75,000 mapviews per month, non-commercial services only.
  • carto-dark - Carto Free usage for up to 75,000 mapviews per month, non-commercial services only.
  • carto-voyager - Carto Free usage for up to 75,000 mapviews per month, non-commercial services only.
  • custom - Pass through the tile URL using parameter tileurl, requires authentication
• attribution - default "osm" - "esri", "osm", "mapbox" or "none" or specify a full URL to a png image - If you add attribution on the image in some other way, you can set this to "none" to hide all logos.
• latitude - optional - Latitude to center the map at. Not needed if using the location parameter, or if specifying one or more markers.
• longitude - optional - Longitude to center the map at.
• location - optional - Free-form text that will be geocoded to center the map. Not needed if specifying a location with the latitude and longitude parameters, or if a marker is specified.
• marker[] - Specify one or more markers to overlay on the map. Parameters are specified as: key:value;. See below for the full list of parameters.
• path[] - Specify one or more paths to draw on the map. See below for the full list of parameters to draw a path.
• polyline - Alternative to path, this allows for a path to be specified as an encoded polyline, allowing for shorter URLs.
• bezier - Specify a bezier curve to your path. 25 will give you a nicely curved line. More Info

Markers

• location - Free-form text that will be geocoded to place the pin
• lat - If a location is not provided, you can specify the location with the lat and lng parameters.
• lng - See above
• icon - Icon to use for the marker. Must choose one of the icons provided in this library, or specify a full URL to a png image. If an invalid icon is specified, the marker will not be rendered. Using a URL required authentication.

Built-In Marker Images

• dot-large-blue
• dot-large-gray
• dot-large-green
• dot-large-orange
• dot-large-pink
• dot-large-purple
• dot-large-red
• dot-large-yellow
• dot-small-blue
• dot-small-gray
• dot-small-green
• dot-small-orange
• dot-small-pink
• dot-small-purple
• dot-small-red
• dot-small-yellow
• fb
• google
• large-blue-blank
• large-blue-cutout
• large-gray-blank
• large-gray-cutout
• large-gray-user
• large-green-blank
• large-green-cutout
• large-orange-blank
• large-orange-cutout
• large-pink-blank
• large-pink-cutout
• large-purple-blank
• large-purple-cutout
• large-red-blank
• large-red-cutout
• large-yellow-blank
• large-yellow-cutout
• large-yellow-message
• large-yellow-user
• small-blue-blank
• small-blue-cutout
• small-gray-blank
• small-gray-cutout
• small-gray-message
• small-gray-user
• small-green-blank
• small-green-cutout
• small-green-user
• small-orange-blank
• small-orange-cutout
• small-pink-blank
• small-pink-cutout
• small-pink-user
• small-purple-blank
• small-purple-cutout
• small-red-blank
• small-red-cutout
• small-yellow-blank
• small-yellow-cutout
• small-yellow-user

Authentication

To be able to use externally-referenced icons or tile URLs, you will need to configure API keys and provide a token in the request. This locks down the ability to fetch external resources to only trusted users of the system.

Create a file data/apikeys.txt and generate a random string with a tool of your choosing, and with one API key per line. Any value passed in the parameter token that matches the text in a line in this file will enable the request to use the restricted features that reference external URLs.

Paths

A path is specified as a list of longitude and latitudes, as well as optional properties to specify the weight and color of the path.

The coordinates of the path are the first value of the property, specified as a list of coordinates similar to GeoJSON.

Examples

Simple path with default color and weight.

path[]=[-122.651082,45.508543],[-122.653617,45.506468],[-122.654183,45.506756]

Specifying the color and weight of the path.

path[]=[-122.651082,45.508543],[-122.653617,45.506468],[-122.654183,45.506756];weight:6;color:0033ff

Polylines

A polyline is an encoded string representing a set of points, as well as optional properties to specify the weight and color of the path.

The encoded polyline first value of the property, followed by the optional color and weight.

Examples

Simple path with default color and weight.

polyline=enc:abcdethtihwithieht3

Specifying the color and weight of the path.

polyline=enc:abcdefghghgk;weight:6;color:0033ff

Examples

Simple map centered at a location

http://static-maps.pdx.esri.com/img.php?basemap=gray&width=400&height=240&zoom=14&latitude=45.5165&longitude=-122.6764

Map with a marker centered at an address

http://static-maps.pdx.esri.com/img.php?marker[]=location:920%20SW%203rd%20Ave,%20Portland,%20OR;icon:small-blue-cutout&basemap=gray&width=400&height=240&zoom=14

Map with an external marker image

http://static-maps.pdx.esri.com/img.php?basemap=gray&width=400&height=240&zoom=14&marker[]=lat:45.5165;lng:-122.6764;icon:http://aaronparecki.com/images/map-pin-green.png

How to install

How to install on a Debian or Ubuntu Server

Install base packages

sudo apt update
sudo apt install git build-essential make bison flex gcc patch autoconf locate libssl-dev curl cmake libjpeg-dev libpng-dev libgif-dev libfreetype6 libfreetype6-dev imagemagick libmagickwand-dev libyaml-dev lynx htop nginx

Install and Configure PHP

sudo apt update
sudo apt install php-fpm php-cli php-curl php-memcache php-dev php-imagick php-gd

Edit /etc/php7.4/fpm/pool.d/www.conf and uncomment the line listen.mode = 0660.

You may have to replace 7.4 with installed version

Restart PHP sudo service php7.4-fpm restart

Configure the virtual host for nginx

Add the below server block to /usr/local/nginx/conf/nginx.conf and remove the default server block.

    server {
        listen 80;
        root /var/www/static-maps-api/public;
	try_files $uri /img.php?$args;

	location ~ \.php$ {
	       fastcgi_pass    unix:/var/run/php7.4-fpm.sock;
	       fastcgi_index   index.php;
               fastcgi_split_path_info ^(.+\.php)(.*)$;
               include fastcgi_params;
               fastcgi_param   SCRIPT_FILENAME $document_root$fastcgi_script_name;
        }
    }

Clone the source

sudo mkdir -p /var/www/static-maps-api
sudo chown -R ubuntu: /var/www
cd /var/www/static-maps-api
git clone git@github.com:dshanske/Static-Maps-API-PHP.git .

License

Original version of code was noted copyright 2013 Esri, Inc. The original version was created by [Aaron Parecki](https://github.com/aaronpk) who has moved on to a newer version of the code in his
[Atlas API](https://github.com/aaronpk/Atlas). Maintenance of the original project, including the backporting of features as well as some additional tweaks, was taken on in 2022 by David Shanske.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.