Skip to main content

Understand Temporary versus Permanent Geocoding

When using the Mapbox Geocoding API, understanding the difference between temporary and permanent geocoding is crucial for compliance with usage terms and optimizing your application's performance and costs.

What is Temporary versus Permanent Geocoding?​

The distinction between temporary and permanent geocoding relates to your usage rights and storage permissions for geocoded coordinate data:

Temporary Geocoding (Default)​

Temporary geocoding is the default mode for all Geocoding API requests. With temporary geocoding:

  • Display permitted: You can display geocoding results on maps and in user interfaces
  • Real-time use allowed: Results can be used for proximity searches, route planning, and other immediate operations
  • Storage restricted: You cannot store the coordinate results for future use
  • Session-based: Results are intended for use during the current user session only

Permanent Geocoding​

Permanent geocoding grants extended usage rights for geocoded data:

  • Storage permitted: You can store coordinate results in databases or local storage
  • Persistent use: Results can be cached and reused across multiple sessions
  • Batch operations: Ideal for processing large datasets where results need to be retained
  • Flexible usage: Stored results can be used for analytics, reporting, and offline applications

When to Use Each Type​

Use Temporary Geocoding When:​

  • Interactive applications: Users are searching for addresses in real-time
  • Live route planning: Converting addresses to coordinates for immediate navigation
  • Search-as-you-type features: Providing instant geocoding feedback during user input
  • One-time lookups: Address validation or location finding without long-term storage needs

Example use cases:

  • Store locator with live search
  • Ride-sharing app pickup/dropoff selection
  • Real estate search with address autocomplete
  • Event location finder

Use Permanent Geocoding When:​

  • Batch processing: Geocoding large datasets of addresses for analysis
  • Data enrichment: Adding coordinates to existing customer or business databases
  • Offline applications: Preprocessing addresses for apps that work without internet connectivity
  • Analytics and reporting: Building datasets for spatial analysis or business intelligence
  • API caching: Storing results to reduce repeated API calls and improve performance

Example use cases:

  • Customer address database enrichment
  • Logistics route optimization with stored waypoints
  • Real estate portfolio analysis
  • Historical data analysis with geographic components

How to Enable Permanent Geocoding​

To use permanent geocoding, add the permanent=true parameter to your Geocoding API request:

// Forward geocoding with permanent storage rights
const response = await fetch(
  'https://api.mapbox.com/geocoding/v5/mapbox.places/1600%20Pennsylvania%20Ave%20NW.json?' +
  'access_token=YOUR_MAPBOX_ACCESS_TOKEN&' +
  'permanent=true'
);

// Reverse geocoding with permanent storage rights  
const response = await fetch(
  'https://api.mapbox.com/geocoding/v5/mapbox.places/-77.036,38.895.json?' +
  'access_token=YOUR_MAPBOX_ACCESS_TOKEN&' +
  'permanent=true'
);

Pricing and Rate Limits​

Temporary Geocoding​

  • Standard geocoding rates apply
  • Typically lower cost per request
  • Standard rate limits

Permanent Geocoding​

  • Higher cost per request due to extended usage rights
  • Same rate limits as temporary geocoding
  • Cost-effective for batch operations where results are reused

Check the current Geocoding API pricing for specific rates.

Was this page helpful?