Developer FAQ

It has been proposed that this page or section be merged with Develop. (Discuss)

This article or section may contain out-of-date information. The information may no longer be correct, or may no longer have relevance.
If you know about the current state of affairs, please help keep everyone informed by updating this information. (Discussion)

in development

Using OSM map tiles

Do you have an API?

Yes, we do - see API.

However, this API is not comparable to (say) the Google Maps API. Our API is for people retrieving and saving raw vector map data, not map images. Our API is mainly intended for the use of map editor software.

If you want to embed a map into a webpage, the Share panel's HTML selection on our website will give you a ready-made chunk of code. For more complex code, such as placing markers on a map, use OpenLayers, Leaflet, Mapstraction, or Static map images instead. If you want, you can even just display OSM maps using the Google API; see Google Maps Example.

Can I use your map tiles in my website/smartphone app?

If you want to use tiles directly from OSM servers, please see Tile usage policy. OpenStreetMap relies on donated and sponsored resources, we do not carry advertising, and we do not charge for any services. We therefore are unable to subsidise heavy third-party usage.

In general, we encourage you to take our raw vector data (from planet.osm) and create your own map tiles from it. Third-party companies also provide tile hosting services.

Why don't we spread the load on the OpenStreetMap database across a number of servers?

Sharing the OSM server load via MySQL replication, or BitTorrent, or carrier pigeon is often recommended, but the idea has so far gained little momentum -- in terms of real development effort. If you have the system administration or coding expertise to implement such a distributed system, please do not hesitate to volunteer on the mailing list.

As a starting point, you may want to familiarise yourself with the existing software infrastructure, as described in the Development pages.

Getting more help

You can get help with OpenLayers at the #openlayers IRC channel at irc.freenode.net. If you're looking to embed a map in your webpage, we request that you ask there and not in the OpenStreetMap IRC channel.

Using OSM map data

I've been blocked from the API for downloading too much. Now what?

Our API is mainly intended for the use of map editor software. It is not suitable for inclusion in your production-release software. Nor is it available for (for example) downloading data for an entire city. As a result, automatic rate limiting is in force, which restricts a very small number of users to avoid impacting on the service for everyone else. The limit is not some sort of game where you try and download at exactly the maximum rate allowed: it's a way of cutting off the people who are downloading vastly more than average.

There are several alternatives:

1. If you want to download map data for specific area, especially filtered one you may use Overpass API
2. For large volume of data see Downloading data
3. If you can live with slightly stale data and don't mind installing Osmosis then you can use a planet dump or an extract from a planet dump. If you can work within the bounds of an existing extract, the whole process is likely to take less than 10 minutes excluding download time - faster than piecemeal downloading from the API (and likely also faster than downloading from XAPI), and with no ill effects on the database.
   • Let's say you want OSM data for London. First of all, download a planet extract for England or Great Britain: https://download.geofabrik.de/europe/great-britain/england-latest.osm.pbf
   • Now, use Osmosis to extract the data for London from this. The left, bottom, right and top parameters here are the latitude/longitude bounding box we have chosen.

osmosis --rbf england-latest.osm.pbf --bb left=-.6 bottom=51.3 right=.4 top=51.7 --wx london.osm

Can I write a script or bot to automatically edit OSM data?

If you wish to script changes to the OSM database then you can do so using the API. However, as such scripts can be very damaging if not done correctly, please read the Automated Edits page and the associated Code of Conduct for some good advice before you start.

Geocoding (placename lookups)

Can I use the OSM database for geocoding?

Our Nominatim system provides this and has an API. Again, please note the usage policy.

Can I download the Nominatim geocoding database?

There is currently no option to do this.

Do you have a complete set of boundary polygons for countries/states?

No, not explicitly. You will need to download planet.osm and process the data, which is not a trivial matter. OSM boundary polygons are not yet complete for all areas. Currently you may find it easier to use another data source for this.

Setting up a renderer

Can I use an Amazon EC2 instance to serve map tiles?

Yes, you can. See TileDrawer and TileMill for ready-made solutions. This blog post explains the pros and cons.

I'm using osm2pgsql. Updates are very slow. How come?

There is a known problem with Postgres 8.4. See the thread at [1].

If you are encountering this problem, try executing:

alter index planet_osm_rels_parts set (fastupdate = off); 
alter index planet_osm_ways_nodes set (fastupdate = off); 
vacuum analyze;

Getting more help

You can get help with Mapnik at the #mapnik IRC channel at irc.freenode.net.

Other questions

HELP! What are all these things I keep hearing about, like API, XAPI, TRAPI, planet, mapnik, osmarender, T@H, ...?

There is an overview that might help you get started finding your way around at Component_overview.

I can't ping the servers. Does that mean the site is down?

No. OpenStreetMap is generously hosted at University College London. Ping is blocked by their network.

I think I found a bug, what should I do?

If you find a problem with a map editing applet (i.e. potlatch, Josm) or the website itself, add it to the OpenStreetMap bug tracking database. We use trac, which uses your OSM username and password.

If you notice something incorrect/missing/wrong/unintelligible with the documentation you're reading right now, edit it! It's a wiki! For wiki advice and extensive documentation, see the mediawiki project, who created the software this wiki is running on.

Why should I not begin development on a new editor, one better/different/prettier than current editors?

There are already several very useful OSM editors in development, and confusing the space with "yet another" platform will only duplicate effort. Please consider contributing to one of the editor development efforts already in progress, such as JOSM, Merkaartor, Potlatch 3, or iD.

Where else to look

• Where to get help?