Back to Website
Guides
Dashboard
Start typing to search…

API Reference

Static maps are standalone images (in JPG or PNG format) that can be displayed on web and mobile devices without the aid of a mapping library or API. Our Static Maps API returns an image in response to an HTTP request. For each request, you can specify the map's location, size of the image, zoom level, type of map. You can also place markers or draw a path at locations on the map.

📘

You can simply embed static map image within an <img> tag's src attribute.

Request

Request Format

Requests can be sent to the following endpoint

GET <https://maps.locationiq.com/v3/staticmap>

Request Example

curl -o mystaticmap.png 'https://maps.locationiq.com/v3/staticmap?key=<YOUR_ACCESS_TOKEN>&center=<latitude>,<longitude>&zoom=<zoom>&size=<width>x<height>&format=<format>&maptype=<MapType>&markers=icon:<icon>|<latitude>,<longitude>&markers=icon:<icon>|<latitude>,<longitude>'
<img src='https://maps.locationiq.com/v3/staticmap?key=<YOUR_ACCESS_TOKEN>&center=<latitude>,<longitude>&zoom=<zoom>&size=<width>x<height>&format=<format>&maptype=<MapType>&markers=icon:<icon>|<latitude>,<longitude>&markers=icon:<icon>|<latitude>,<longitude>'>
<img src='https://maps.locationiq.com/v3/staticmap?key=<YOUR_ACCESS_TOKEN>&center=<latitude>,<longitude>&zoom=<zoom>&size=<width>x<height>&format=<format>&maptype=<MapType>&markers=icon:<icon>|<latitude>,<longitude>&markers=icon:<icon>|<latitude>,<longitude>'>
<img src='https://maps.locationiq.com/v3/staticmap?key=<YOUR_ACCESS_TOKEN>&center=<latitude>,<longitude>&zoom=<zoom>&size=<width>x<height>&format=<format>&maptype=<MapType>&markers=icon:<icon>|<latitude>,<longitude>&markers=icon:<icon>|<latitude>,<longitude>'>

Requests Parameters

Name

Description

Required

Values

key

Authentication key.

Yes

Access token

center

Defines the center of the map. It takes a comma separated value of a latitude, longitude pair. This parameter is required if markers are not defined.

Either

Latitude [-90 to 90], Longitude [-180 to 180]

zoom

Set the zoom level for the map. Required if markers are not present. Defaults to 18

Yes

[0 to 18]

scale

Affects the number of pixels that are returned. Defaults to 1.

No

[1,2].

size

Defines the rectangular dimensions of the map image. This parameter takes a string of the form {width}x{height}. Defaults to 300x300. The maximum allowed size is 1280x1280. The dimensions of the response image depend on the size and scale values as {scale x width} x {scale x height}. For example, if scale=2, and size=300x300, the dimensions of the output image will be 600x600. If you need larger image sizes, reach out to us!

No

<string>

format

Defines the format of the resulting image. Defaults to png. JPG is recommended for optimal performance and reduced file size.

No

[jpeg | jpg | png][jpeg | jpg | png]

maptype

Defines the style/ theme of the map to construct. Defaults to streets

No

[streeets | light | dark][streeets \| light \| dark]

markers

Defines markers to overlay on the map. Parameters are specified as key:value separated by Pipe character. See below for the full list of parameters. Required if center is not set.

Either

path

Defines a path to draw on the map. Path parameters are separated by Pipe character. (See below for the full list of parameters)

No

linecap

This property determines the shape used to draw the endpoints of the paths.

  • Butt : The ends of lines are squared off at the endpoints.
  • Round: The ends of lines are rounded.
  • Square: The ends of lines are squared off by adding a box with an equal width and half the height of the line's thickness.

No

butt(default)/
round /
square

linejoin

This property determines the shape used to join two path segments where they meet.

  • Round: Rounds off the corners of a shape by filling an additional sector of disc centered at the common endpoint of connected segments. The radius for these rounded corners is equal to the line width.
  • Bevel: Fills an additional triangular area between the common endpoint of connected segments and the separate outside rectangular corners of each segment.
  • Miter: Joins connected segments by extending their outside edges to connect at a single point, filling an additional lozenge-shaped area. This setting is affected by the miterLimit property.

No

round /
bevel /
miter (default)

Markers

Markers are a type of overlay used to identify locations on the map. The markers parameter accepts a set of values in the following format:

markers=icon:<icon_name>|markerStyles|markerLocation&markers=icon:<icon_name>|markerStyles|markerLocation

For using same icon-name for all markerLocations, you can send multiple markerLocations in the same markers parameter.

markers=icon:<icon_name>|markerLocation|markerLocation|..
curl -o mystaticmap.png 'https://maps.locationiq.com/v3/staticmap?key=<YOUR_ACCESS_TOKEN>&size=600x600&zoom=14&markers=45.5165,-122.6764|icon:large-blue-cutout&format=jpg'

Below are the list of values that are accepted by markers param :

  • icon : Icon to use for the marker. Must choose one of the icons mentioned below. If an invalid icon is specified, the marker will not be rendered. Below are the available icon names :
LargeSmallTinyLarge-BlankSmall-BlankTiny-Blank
large-red-cutout.png large-red-cutoutsmall-red-cutout.png small-red-cutouttiny-red-cutout.png tiny-red-cutoutlarge-red-blank.png large-red-blanksmall-red-blank.png small-red-blanktiny-red-blank.png tiny-red-blank
large-blue-cutout.png large-blue-cutoutsmall-blue-cutout.png small-blue-cutouttiny-blue-cutout.png tiny-blue-cutoutlarge-blue-blank.png large-blue-blanksmall-blue-blank.png small-blue-blanktiny-blue-blank.png tiny-blue-blank
large-gray-cutout.png large-gray-cutoutsmall-gray-cutout.png small-gray-cutouttiny-gray-cutout.png tiny-gray-cutoutlarge-gray-blank.png large-gray-blanksmall-gray-blank.png small-gray-blanktiny-gray-blank.png tiny-gray-blank
large-yellow-cutout.png large-yellow-cutoutsmall-yellow-cutout.png small-yellow-cutouttiny-yellow-cutout.png tiny-yellow-cutoutlarge-yellow-blank.png large-yellow-blanksmall-yellow-blank.png small-yellow-blanktiny-yellow-blank.png tiny-yellow-blank
large-purple-cutout.png large-purple-cutoutsmall-purple-cutout.png small-purple-cutouttiny-purple-cutout.png tiny-purple-cutoutlarge-purple-blank.png large-purple-blanksmall-purple-blank.png small-purple-blanktiny-purple-blank.png tiny-purple-blank
large-orange-cutout.png large-orange-cutoutsmall-orange-cutout.png small-orange-cutouttiny-orange-cutout.png tiny-orange-cutoutlarge-orange-blank.png large-orange-blanksmall-orange-blank.png small-orange-blanktiny-orange-blank.png tiny-orange-blank
large-green-cutout.png large-green-cutoutsmall-green-cutout.png small-green-cutouttiny-green-cutout.png tiny-green-cutoutlarge-green-blank.png large-green-blanksmall-green-blank.png small-green-blanktiny-green-blank.png tiny-green-blank
large-black-cutout.png large-black-cutoutsmall-black-cutout.png small-black-cutouttiny-black-cutout.png tiny-black-cutoutlarge-black-blank.png large-black-blanksmall-black-blank.png small-black-blanktiny-black-blank.png tiny-black-blank

  • markerLocation : Each markerLocation param should contain latitude, longitude pair which defines the position of the marker.

    • Example: markers=icon:large-red-cutout|17.451377,78.379525|17.450419,78.381149

  • markerStyles : consists of visual attributes like size and color, which are used to display the markers on the map.

    • size : accepted values - [tiny, small, large]. Defaults to small.
    • color : accepted values - [blue, gray, red, yellow, orange, green, purple]. Defaults to red.
    • Example: markers=size:small|color:red|17.451377,78.379525|17.450419,78.381149

Available Themes

ThemeFormatImage
streetsraster (png/ jpg/ jpeg)streets image
darkraster (png/ jpg/ jpeg)dark image
lightraster (png/ jpg/ jpeg)light image

Example:

https://maps.locationiq.com/v3/staticmap?key={{Your_API_Key}}&zoom=14&size=600x600&format=png&maptype=dark&markers=icon:large-purple-cutout%7C45.5165,-122.6764

Path

The path parameter defines a set of one or more locations connected by a path to overlay on the map image. The path parameter takes set of values in the following format:

path=pathStyles|pathLocation1|pathLocation2|... etc.

📘

To avoid decoding issues when using an encoded polyline in your request, we recommend that you place the style information first, followed by the polyline inside the path variable.

Below are the list of values that are accepted by path parameter :

  • pathStyles : consists of visual attributes to use when displaying the path.
    • weight : specifies the thickness of the path in pixels.
    • color : color of the path stroke (e.g. red, rgba(255,255,255,0.5), #0000ff)
    • fillcolor : color to use as the fill (e.g. red, rgba(255,255,255,0.5), #0000ff)
    • Example: path=weight:2|color:blue|fillcolor:%23add8e6|17.452945,78.380055|17.452765,78.382026
  • pathLocation :
    • Using coordinates: Each pathLocation parameter contains latitude, longitude pair seperated by comma.
      • Format: path=lat1,lon1|lat2,lon2|
      • Example: https://maps.locationiq.com/v3/staticmap?key=YOUR_ACCESS_TOKEN&center=17.450419,78.381149&size=600x600&zoom=14&format=jpg&path=fillcolor:%2390EE90|weight:2|color:blue|17.452945,78.380055|17.452765,78.382026|17.452020,78.381375|17.452045,78.380846|17.452945,78.380055
    • Using an encoded polyline: Prefix with enc: followed by the encoded polyline string
      • Format: path=enc:<encoded_polyline
      • Example: https://maps.locationiq.com/v3/staticmap?key=YOUR_ACCESS_TOKEN&center=17.450419,78.381149&size=600x600&zoom=14&format=jpg&path=fillcolor:%2390EE90|weight:2|color:blue|enc:}woiBkrk}Mb@iKtCCEhBsD|C\\

Example

Below is the sample static map having two markers, polygonal area and is centered at 17.450419,78.381149.

https://maps.locationiq.com/v3/staticmap?key=<YOUR_ACCESS_TOKEN>&center=17.450419,78.381149&zoom=16&format=jpg&size=480x480&markers=icon:large-red-cutout|17.450419,78.381149&markers=icon:large-red-cutout|17.451377,78.379525&path=fillcolor:%23add8e6|weight:1|color:blue|17.452945,78.380055|17.452765,78.382026|17.452020,78.381375|17.452045,78.380846|17.452945,78.380055

Errors

For all errors except authentication errors, the Static Map API returns the following blank image in grey to help preserve user experience. An error code is set in the HTTP Response code as per the Errors section.

Authentication errors will return JSON in the format specified in the Errors section.

Updated 3 days ago