Authentication overview

MapQuest's API services, including its Geocoding, Mapping, Directions, and Search APIs, secure access primarily through API keys. These keys serve as unique identifiers for applications, enabling MapQuest to track usage, enforce rate limits, and authorize requests against a developer's account. This method provides a straightforward way for developers to integrate MapQuest functionalities into their applications while maintaining a level of control over access and consumption of services.

An API key is a token that a client provides when making API calls. It acts as a project identifier and provides authorization. When a request is made to a MapQuest API endpoint, the API key is typically included as a query parameter in the URL. MapQuest's infrastructure then validates this key against registered applications to ensure the request is legitimate and to associate it with the correct account for billing and usage tracking purposes. This approach is common among many web service providers for public-facing APIs and is particularly suitable for client-side applications where user authentication is handled separately or not required for the API itself.

While API keys offer simplicity, their security relies heavily on proper management and restriction. Unlike more complex authentication schemes like OAuth 2.0, API keys alone do not provide mechanisms for user consent or delegated authorization. Best practices recommend implementing additional security measures, such as referrer or IP restrictions, to mitigate potential misuse if a key is compromised. The MapQuest developer portal provides tools to manage and secure these keys effectively, allowing developers to configure these restrictions.

Supported authentication methods

MapQuest primarily supports API key authentication across all its services. This method is designed for ease of use and quick integration, making it suitable for a wide range of applications, from web-based mapping tools to server-side geocoding processes. The simplicity of API keys means developers can get started quickly without extensive configuration of complex authentication flows.

The API key is a simple string that identifies your application and authorizes access. It is passed directly in the request URL. MapQuest does not currently support more advanced authentication protocols such as OAuth 2.0 or mutual TLS for its public-facing APIs. For scenarios requiring user-specific authorization or more granular access control, developers typically implement their own user authentication system on top of the MapQuest API key-based access.

Below is a table summarizing the supported authentication method:

Method When to Use Security Level
API Key Public APIs, client-side applications, server-side scripts, quick integration. Moderate (requires careful management and restrictions).

For a broader understanding of API authentication methods, the OAuth 2.0 specification is a widely adopted framework for delegated authorization, though it is not directly implemented by MapQuest for API access.

Getting your credentials

To use MapQuest APIs, you need to obtain an API key from the developer portal. The process involves registering an account and creating an application, which then generates the unique key.

  1. Create a MapQuest Developer Account: Navigate to the MapQuest developer homepage and sign up for a new account. This typically involves providing an email address and creating a password.
  2. Access the Dashboard: Once registered and logged in, you will be directed to your developer dashboard.
  3. Create a New Application: Within the dashboard, you'll find an option to 'Create a New Key' or 'Create an Application'. Click this to start the process.
  4. Name Your Application: Provide a descriptive name for your application (e.g., "My Web Mapping Project" or "Backend Geocoding Service"). This helps you identify the key's purpose later.
  5. Generate the Key: After naming your application, MapQuest will generate a unique API key for it. This key will be displayed on your dashboard.
  6. Configure Key Restrictions (Optional but Recommended): For enhanced security, you can configure restrictions for your API key. This might include:
    • HTTP Referrers: Specify the domains from which API requests can originate (e.g., *.yourdomain.com/*). This is crucial for client-side JavaScript applications.
    • IP Addresses: List specific IP addresses or CIDR blocks that are authorized to use the key. This is ideal for server-side applications.
    These restrictions help prevent unauthorized use of your API key if it is accidentally exposed. You can find detailed instructions on setting up these restrictions in the MapQuest API documentation.

It is important to store your API key securely and never embed it directly in publicly accessible client-side code without appropriate referrer restrictions. Treat your API key like a password.

Authenticated request example

Once you have obtained your API key, you can include it in your API requests. For MapQuest APIs, the key is typically passed as a query parameter named key in the URL.

Geocoding API Example (cURL)

This example demonstrates how to make a request to the MapQuest Geocoding API to geocode an address using a placeholder API key. Replace YOUR_API_KEY with your actual key.

curl -X GET \
  'https://www.mapquestapi.com/geocoding/v1/address?key=YOUR_API_KEY&location=1600+Amphitheatre+Parkway,+Mountain+View,+CA' \
  -H 'Accept: application/json'

In this cURL command, YOUR_API_KEY is the placeholder for the key you generated. The location parameter specifies the address to be geocoded. The -H 'Accept: application/json' header indicates that the client prefers to receive the response in JSON format.

JavaScript SDK Example

When using the MapQuest JavaScript SDK, the API key is typically configured during the initialization of the map or other service components. The SDK handles the inclusion of the key in subsequent API calls automatically.

L.mapquest.key = 'YOUR_API_KEY';

var map = L.mapquest.map('map', {
  center: [39.7392, -104.9903],
  layers: L.mapquest.tileLayer('map'),
  zoom: 10
});

L.mapquest.geocoding().geocode('1600 Amphitheatre Parkway, Mountain View, CA', function (error, response) {
  if (error) {
    console.error(error);
    return;
  }
  console.log(response.results[0].locations[0].latLng);
});

In this JavaScript example, L.mapquest.key = 'YOUR_API_KEY'; sets the global API key for the MapQuest JavaScript library. Subsequent calls to L.mapquest.map() or L.mapquest.geocoding().geocode() will automatically use this key. For more detailed SDK usage, refer to the MapQuest JavaScript SDK documentation.

Security best practices

While API keys offer simplicity, securing them is crucial to prevent unauthorized usage and protect your account from exceeding transaction limits. Adhering to these best practices will help maintain the integrity of your MapQuest integration:

  1. Restrict API Keys: Always apply referrer or IP address restrictions to your API keys. This is the most effective way to limit what can be done if your key is exposed. For web applications, configure HTTP referrer restrictions to allow requests only from your authorized domains. For server-side applications, restrict by IP address to permit requests only from your server's IP. This prevents others from using your key even if they discover it. The MapQuest developer dashboard provides tools to configure these restrictions.
  2. Do Not Embed Keys Directly in Public Client-Side Code: Avoid hardcoding API keys directly into client-side JavaScript that is publicly accessible. While referrer restrictions mitigate some risks, it's generally safer to proxy requests through your own backend server, especially if you need to perform more sensitive operations or if you cannot sufficiently restrict the key.
  3. Use Environment Variables for Server-Side Keys: For server-side applications, store API keys in environment variables rather than directly in your source code. This practice prevents the key from being committed to version control systems (like Git) and makes it easier to manage keys across different deployment environments (development, staging, production).
  4. Regularly Rotate API Keys: Periodically generate new API keys and revoke old ones. This practice, known as key rotation, reduces the window of opportunity for a compromised key to be exploited. Many security frameworks, such as those discussed by the IETF RFC 6749 for OAuth 2.0, recommend regular credential rotation as a fundamental security measure, a principle applicable even to simpler API keys.
  5. Monitor API Usage: Regularly check your MapQuest API usage reports in your developer dashboard. Unexpected spikes in usage could indicate that your API key has been compromised. Timely detection allows you to revoke the key and investigate the cause.
  6. Secure Your Developer Account: Use a strong, unique password for your MapQuest developer account. If available, enable multi-factor authentication (MFA) to add an extra layer of security to your account login.
  7. Revoke Compromised Keys Immediately: If you suspect an API key has been compromised, revoke it immediately from your MapQuest developer dashboard. Then, generate a new key and update your applications accordingly.

By implementing these security measures, you can significantly reduce the risk associated with using API keys and maintain a secure integration with MapQuest services.