> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/help/llms.txt)

# Understand Temporary versus Permanent Geocoding

When using the [Mapbox Geocoding API](https://docs.mapbox.com/api/search/geocoding/), 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:

```javascript
// 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](https://www.mapbox.com/pricing/) for specific rates.

## Related Resources

-   [Mapbox Geocoding API Documentation](https://docs.mapbox.com/api/search/geocoding/)
-   [Geocoding API Pricing](https://www.mapbox.com/pricing/)
-   [Rate Limiting Best Practices](https://docs.mapbox.com/api/overview/#rate-limits)
-   [Terms of Service](https://www.mapbox.com/legal/tos/)