OpenStreetMap Getting Started: Account, Keys, First Request (2026)

Getting started overview

OpenStreetMap (OSM) provides a global dataset of geographic information, maintained by a community of contributors. Unlike commercial mapping platforms that offer proprietary APIs, OSM primarily provides the raw data. Developers typically interact with OSM data through various open-source tools and services built upon it, or via third-party providers who host and manage OSM-based APIs. The primary way to get started with OpenStreetMap for development, especially for tasks like geocoding (converting addresses to coordinates) or reverse geocoding (coordinates to addresses), involves using a service like Nominatim.

Nominatim is an open-source search engine for OSM data, allowing queries for locations and addresses. While it is possible to self-host a Nominatim instance, many developers opt for publicly available Nominatim instances or commercial alternatives that provide managed APIs with rate limits and support. For initial development, using a public Nominatim instance is common, though it's important to respect their usage policies.

This guide focuses on the streamlined process of setting up your environment for basic geocoding with OpenStreetMap data using a publicly available Nominatim instance, covering account creation (for contributions, not strictly for API keys), understanding how to make requests, and common next steps for integration into development projects.

Create an account and get keys

To use OpenStreetMap data, you typically do not need API keys from OpenStreetMap directly. OpenStreetMap's core offering is the data itself, which is open-source. However, creating an OpenStreetMap account is useful for several reasons:

• Contributing data: An account allows you to edit and improve the map data, which is a fundamental aspect of the OpenStreetMap project.
• Personalization: Some OSM-based services or applications might allow login with your OSM account for personalized settings or saved locations.
• Project identification: When using public Nominatim instances, including a descriptive User-Agent header that identifies your application and provides contact information is often requested as part of their usage policy. While not an API key, it serves a similar purpose for identifying requests.

Steps to create an OpenStreetMap account:

1. Navigate to the OpenStreetMap registration page.
2. Enter your desired username, email address, and create a password.
3. Accept the terms of service.
4. You will receive an email to verify your account. Follow the instructions in the email to complete the registration.

Once your account is created, you can log in to the OpenStreetMap website. For most development tasks involving geocoding, this account does not directly provide an API key. Instead, you'll interact with a service like Nominatim, which uses the open data directly. If you plan to use a commercial API built on OpenStreetMap data, that provider will furnish specific API keys and instructions; for example, some providers might require registration and provide a token for authentication similar to Google Maps API keys.

Your first request

For your first request, we will use a public Nominatim instance to perform a simple geocoding query. This demonstrates how to translate a human-readable address into geographic coordinates (latitude and longitude).

Example: Geocoding an address with Nominatim

The Nominatim API is typically accessed via HTTP GET requests. The base URL for the official public Nominatim instance is https://nominatim.openstreetmap.org/.

Request structure:

To geocode an address, you'll use the /search endpoint. Key parameters include:

• q: The query string (the address or place name).
• format: The desired output format (e.g., json, xml).
• limit: The maximum number of results to return.
• addressdetails: Set to 1 to include detailed address information.

Remember to include a User-Agent header for responsible usage when interacting with public services, as detailed in the Nominatim Usage Policy. A well-formed User-Agent helps the service administrators understand who is making requests and provides a contact point in case of issues.

Example HTTP GET Request (via cURL):

curl -X GET \
  "https://nominatim.openstreetmap.org/search?q=1600+Amphitheatre+Parkway,+Mountain+View,+CA&format=json&limit=1&addressdetails=1" \
  -H "Accept: application/json" \
  -H "User-Agent: MyTestApp/1.0 ([email protected])"

Example Response (simplified JSON):

[
  {
    "place_id": 28189812,
    "licence": "Data © OpenStreetMap contributors, ODbL. OpenStreetMap Foundation. www.openstreetmap.org/copyright",
    "osm_type": "node",
    "osm_id": 271239845,
    "boundingbox": [
      "37.4219",
      "37.4220",
      "-122.0841",
      "-122.0840"
    ],
    "lat": "37.4219999",
    "lon": "-122.0840575",
    "display_name": "1600, Amphitheatre Parkway, Mountain View, Santa Clara County, California, 94043, United States",
    "class": "place",
    "type": "house",
    "importance": 0.6,
    "address": {
      "house_number": "1600",
      "road": "Amphitheatre Parkway",
      "city": "Mountain View",
      "county": "Santa Clara County",
      "state": "California",
      "postcode": "94043",
      "country": "United States",
      "country_code": "us"
    }
  }
]

Key elements in the response:

• lat and lon: The latitude and longitude of the geocoded location.
• display_name: A human-readable full address string.
• address object: Contains structured address components.

Common next steps

After successfully performing a basic geocoding request, consider these common next steps for integrating OpenStreetMap data into your applications:

1. Integrate a mapping library: To display maps in a web or mobile application, integrate a mapping library such as Leaflet.js (for web) or OpenLayers. These libraries allow you to render OSM tiles and overlay your geocoded points. Many public and private tile servers are available; for example, OpenStreetMap's wiki lists various tile servers.
2. Advanced geocoding and reverse geocoding: Explore more advanced features of Nominatim, such as searching by bounding box, querying for specific types of places, or performing reverse geocoding (finding an address from coordinates). Refer to the Nominatim API documentation for a comprehensive list of parameters.
3. Consider a managed OpenStreetMap API: For production applications requiring higher rate limits, guaranteed uptime, and dedicated support, consider using a commercial provider that offers a managed API built on OpenStreetMap data. Examples include Mapbox (which uses OSM data), or others that specialize in hosted Nominatim services. This offloads the operational burden of self-hosting and scaling.
4. Data Contribution: If your project involves collecting or improving geographic data, learn how to contribute back to OpenStreetMap. This can be done through various editors like iD Editor or JOSM. The OpenStreetMap Beginner's Guide is a good starting point.
5. Explore other OSM-based services: Beyond Nominatim, the OpenStreetMap ecosystem includes routing engines (e.g., OSRM, GraphHopper), spatial databases (e.g., PostGIS with OSM data), and custom rendering tools. Each serves different geospatial needs and offers its own API or integration methods.

Troubleshooting the first call

When making your first request to a Nominatim instance, you might encounter issues. Here are common problems and their solutions:

Summary of getting started steps

Common troubleshooting scenarios:

• 403 Forbidden / Rate Limit Exceeded: Public Nominatim instances have usage policies and rate limits. Frequent or un-identified requests can lead to temporary blocks. Ensure you include a unique and descriptive User-Agent header and respect the Nominatim Usage Policy. If you need higher limits, consider self-hosting or a commercial provider.
• No results found:
  • Query inaccuracy: Ensure your query string (q parameter) is accurate. Try simpler or more specific addresses.
  • Encoding issues: URLs should be properly URL-encoded. Spaces in addresses, for example, should be replaced with %20 or +. Many HTTP client libraries handle this automatically.
• CORS errors (Cross-Origin Resource Sharing): If you are making requests directly from a web browser (e.g., via JavaScript in a front-end application), the public Nominatim instance might not allow direct cross-origin requests. Solutions include using a proxy server on your backend to forward requests, or using a mapping library that handles API calls securely.
• Incorrect JSON parsing: Verify your code correctly parses the JSON response. Ensure your Accept header is set to application/json and that your JSON parsing library is configured correctly.
• Service availability: Occasionally, public instances may experience downtime or maintenance. Check the OpenStreetMap community channels or relevant service status pages if you suspect an outage.

For persistent issues, reviewing the Nominatim documentation and community forums can provide further insights. Additionally, for complex use cases or production environments, professional support from commercial OpenStreetMap API providers can be beneficial.