One Map, Singapore Getting Started: API Access & First Request (2026)

Getting started overview

To begin using One Map, Singapore's geospatial services, developers can immediately access basic APIs without registration or an API key. This allows for immediate experimentation with functionalities like basic search or geocoding. For applications requiring higher request volumes, access to enhanced APIs, or more consistent performance, registering for an API key is recommended. The registration process is straightforward and provides credentials that authenticate requests to the One Map, Singapore platform. Once an API key is obtained, it is incorporated into API calls, typically as a query parameter or header, to access the desired geospatial data or services.

The core process involves:

1. Optional Registration: Create an account on the developer portal to obtain an API key.
2. API Key Generation: Generate a unique API key from your developer dashboard.
3. First API Call: Construct an HTTP request to a One Map, Singapore endpoint, including your API key if registered.
4. Response Processing: Handle the JSON response from the API.

This guide will walk through these steps to ensure you can make a successful first request and begin building applications with Singapore's national geospatial platform.

Quick Reference: One Map, Singapore Getting Started

Create an account and get keys

While basic One Map, Singapore APIs can be accessed without an API key, registration offers advantages such as increased rate limits and access to specific enhanced services. The One Map, Singapore platform supports free usage for both registered and unregistered users, with rate limits applied based on whether an API key is used.

Account Creation Steps:

1. Navigate to the One Map, Singapore developer signup page.
2. Provide the required information, which typically includes an email address and a password.
3. Complete any verification steps, such as email confirmation.
4. Once registered, log in to your developer dashboard.

Obtaining Your API Key:

After successfully creating and logging into your account, you can generate an API key:

1. From your developer dashboard, locate the section for API key management. The exact navigation may vary but is usually labeled 'API Keys' or similar.
2. Click on an option to 'Generate New API Key' or 'Create API Key'.
3. A unique API key will be displayed. It is crucial to store this key securely, as it authenticates your applications' requests to the One Map, Singapore services. The One Map, Singapore API Key documentation provides further details on best practices for key management.

This API key will be included in your API requests to identify your application and ensure you benefit from the higher rate limits associated with registered users. Without an API key, requests are still processed but may be subject to stricter rate limiting for unregistered access.

Your first request

To make your first request to One Map, Singapore, we will use the Search API, which allows you to find addresses or points of interest within Singapore. This example demonstrates a basic search for a specific location. You can make this request using a command-line tool like cURL or through a programming language's HTTP client.

Example: Search for an Address

This example searches for 'orchard road'. If you obtained an API key, replace YOUR_API_KEY with your actual key. If you are not using an API key, you can omit the token parameter, though you will be subject to unregistered rate limits.

Using cURL:

Open your terminal or command prompt and execute the following cURL command:

curl -X GET "https://developers.onemap.sg/commonapi/search?searchVal=orchard%20road&returnGeom=Y&getAddrInfo=Y&pageNum=1&token=YOUR_API_KEY"

Replace YOUR_API_KEY with the key you generated. If you are not using an API key, the parameter &token=YOUR_API_KEY can be removed, and the request will still function for basic searches.

Using JavaScript (Node.js with fetch):

This JavaScript example uses the node-fetch library, which mimics the browser's fetch API. First, install node-fetch: npm install node-fetch. Then, create a .js file and add the following code:

import fetch from 'node-fetch';

const apiKey = 'YOUR_API_KEY'; // Replace with your actual API key, or remove if not using
const searchVal = 'orchard road';
const pageNum = 1;

const url = `https://developers.onemap.sg/commonapi/search?searchVal=${encodeURIComponent(searchVal)}&returnGeom=Y&getAddrInfo=Y&pageNum=${pageNum}${apiKey ? `&token=${apiKey}` : ''}`;

fetch(url)
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log('Search Results:', JSON.stringify(data, null, 2));
    if (data.results && data.results.length > 0) {
      console.log('First Result Address:', data.results[0].ADDRESS);
    }
  })
  .catch(error => {
    console.error('Error fetching data:', error);
  });

Remember to replace YOUR_API_KEY or remove the token parameter if not using an API key.

Expected Response Structure:

A successful request will return a JSON object containing search results. The structure will typically include a results array, where each object represents a matched location with details such as ADDRESS, LATITUDE, and LONGITUDE.

{
  "found": 1,
  "totalNumPages": 1,
  "pageNum": 1,
  "results": [
    {
      "SEARCHVAL": "ORCHARD ROAD",
      "BLK_NO": "",
      "ROAD_NAME": "ORCHARD ROAD",
      "BUILDING": "",
      "ARCHIVE_DATE": "2026-05-29",
      "LATITUDE": "1.3049103814421",
      "LONGITUDE": "103.831517596826",
      "X": "28503.220",
      "Y": "31498.406",
      "POSTAL": "",
      "ADDRESS": "ORCHARD ROAD"
    }
  ]
}

This response confirms that your request was successfully processed and provides geographical information for 'orchard road' in Singapore.

Common next steps

After successfully making your first request to One Map, Singapore, several directions can enhance your application's geospatial capabilities:

1. Explore Other APIs: One Map, Singapore offers a suite of APIs beyond basic search. Consider integrating the Geocoding API to convert addresses to coordinates, the Reverse Geocoding API to convert coordinates to addresses, or the Routing API for calculating directions.

2. Implement Error Handling: Robust applications include error handling to manage API responses that are not successful (e.g., HTTP 4xx or 5xx status codes). Refer to the One Map, Singapore API documentation for specific error codes and messages.

3. Integrate with a Mapping Library: To display search results visually, integrate One Map, Singapore data with mapping libraries like Leaflet or OpenLayers. These libraries allow you to render maps, markers, and other geographical features using the latitude and longitude coordinates obtained from One Map, Singapore APIs. For instance, ArcGIS Developers provides resources for integrating geospatial data into web applications.

4. Manage API Key Security: If you are using an API key, ensure it is protected. Avoid hardcoding API keys directly into client-side code that could be publicly exposed. For server-side applications, store keys in environment variables or a secure configuration management system. For client-side applications, consider proxying requests through your own backend to conceal the key.

5. Monitor Usage and Rate Limits: Keep track of your API usage, especially if your application scales. One Map, Singapore has rate limits, and understanding your consumption can prevent service interruptions. Information on API key usage and limits is available in the developer portal.

6. Explore Thematic Maps: One Map, Singapore also offers Thematic Map services, which allow developers to overlay specific datasets (e.g., property boundaries, planning areas) onto base maps. This can be useful for applications requiring specialized geographical context.

Troubleshooting the first call

Encountering issues with your initial API call is common. Here are some troubleshooting steps for One Map, Singapore APIs:

• Verify API Key (if applicable): Double-check that your API key is correctly included in the URL as the token parameter and that it matches the key generated in your developer dashboard. An incorrect or expired key will result in authentication failures. Refer to the API Key documentation for details.

• Check URL Encoding: Ensure that all query parameters, especially searchVal, are properly URL-encoded. Spaces and special characters must be converted (e.g., space to %20). Most HTTP client libraries handle this automatically, but manual construction requires careful encoding. Mozilla Developer Network provides documentation on encodeURIComponent for JavaScript.

• Review Endpoint URL: Confirm that the base URL and endpoint path are exactly as specified in the One Map, Singapore API reference. Typos in the URL can lead to 404 Not Found errors.

• Inspect HTTP Status Code: The HTTP status code returned by the API provides critical information:

  • 200 OK: The request was successful. Check the response body for the expected data.
  • 400 Bad Request: Often indicates missing or malformed parameters. Review your request parameters against the API documentation.
  • 401 Unauthorized: Typically means an invalid or missing API key.
  • 403 Forbidden: May indicate rate limit exceeded or insufficient permissions for the API key.
  • 404 Not Found: Incorrect endpoint URL.
  • 5xx Server Error: An issue on the One Map, Singapore server side. These are less common but can occur.

• Examine Response Body for Error Messages: Even with a non-200 status code, the API often returns a JSON body with detailed error messages. Parse this response to understand the specific issue.

• Check Rate Limits: If you are making many requests, you might be hitting rate limits. One Map, Singapore implements limits, especially for unregistered users. Registered users with API keys have higher limits. Wait a short period and try again, or register for an API key if you haven't already.

• Consult Documentation and Community: The One Map, Singapore developer portal is the primary resource for troubleshooting. If the issue persists, check if there's a developer forum or support channel linked on the portal.