ViaCep

Overview

ViaCep offers a specialized API for retrieving Brazilian address information based on a given Postal Code (CEP). Since its inception in 2013, the service has focused exclusively on the Brazilian territory, providing a reliable and free resource for developers. The API is designed to be straightforward, allowing for quick integration into various systems that require accurate address data for locations within Brazil.

The primary function of ViaCep is to convert a Brazilian CEP into a complete address, including street name, neighborhood, city, and state. This capability is essential for businesses operating in Brazil, particularly in sectors such as e-commerce, logistics, and financial services. For instance, online retailers can use ViaCep to validate customer shipping addresses at the point of sale, reducing delivery errors and improving customer satisfaction. Logistics companies can integrate the API to streamline route planning and package delivery, ensuring that shipments reach their correct destinations efficiently. The service also supports auto-completion features in forms, enhancing user experience by pre-filling address fields as users type their CEPs, which can reduce data entry mistakes and accelerate checkout processes.

ViaCep's API is accessible via standard HTTP requests and supports multiple response formats, including JSON, XML, and plain text. This flexibility allows developers to choose the format that best fits their application's architecture. The service is entirely free to use, without rate limits or authentication requirements, making it a highly accessible option for developers and organizations of all sizes. This contrasts with many global geocoding services that typically operate on a freemium or paid model. For projects specifically targeting the Brazilian market, ViaCep provides a focused solution without the overhead of integrating and managing a more complex global geocoding platform. The simplicity and dedicated focus on Brazilian data make it a practical choice for developers building applications that need to process or validate Brazilian addresses with precision and ease.

While ViaCep is highly effective for Brazilian CEP lookups, it does not provide global geocoding services or reverse geocoding (converting coordinates to addresses). Its scope is intentionally narrow, concentrating on providing comprehensive and accurate data for Brazilian postal codes as maintained by Correios, the national postal service of Brazil. Developers needing broader international coverage or advanced geocoding functionalities might consider supplementing ViaCep with other services, as discussed in the alternatives section. However, for its specific niche, ViaCep remains a prominent solution due to its cost-free model and consistent performance for Brazilian address data requests.

Key features

• CEP Lookup API: Provides a simple RESTful interface to retrieve full address details (street, neighborhood, city, state) from a Brazilian CEP.
• Address Validation: Helps verify the existence and details of a Brazilian address based on its CEP, reducing data entry errors and improving data quality.
• Multiple Response Formats: Supports JSON, XML, and plain text response formats, allowing developers to integrate data seamlessly into various application environments.
• No Authentication Required: The API does not require API keys or tokens, simplifying the integration process and reducing setup time.
• Unlimited Free Requests: Offers unlimited requests without any associated costs, making it a budget-friendly option for all project scales.
• Fast Response Times: Designed for low latency, providing quick address lookups essential for real-time applications like e-commerce checkouts.
• Broad Language Support: While not official SDKs, community-contributed libraries exist for popular languages like JavaScript, Python, PHP, Ruby, Java, C#, and Go, facilitating development.

Pricing

ViaCep operates on an entirely free model, offering unlimited requests without any cost. This pricing structure has been consistent since its inception and is detailed in the official API documentation.

Pricing as of 2026-05-28. For the most current details, refer to the ViaCep API documentation.

Common integrations

ViaCep's straightforward API design facilitates integration with various platforms and custom applications. While it doesn't offer official SDKs, its RESTful nature means it can be consumed by any language or platform capable of making HTTP requests. Common integration scenarios include:

• E-commerce Platforms: Integrating with checkout flows on platforms like Shopify (via custom apps), WooCommerce, or Magento to validate Brazilian shipping addresses automatically.
• CRM Systems: Enhancing customer relationship management systems (e.g., Salesforce via Apex or external integrations, Salesforce developer guides) to ensure accurate contact information for Brazilian clients.
• ERP Solutions: Connecting with enterprise resource planning systems for accurate address data in order fulfillment, invoicing, and logistics modules.
• Logistics and Delivery Applications: Used by internal systems for route optimization, delivery confirmation, and fraud prevention for Brazilian shipments.
• Mobile Applications: Incorporating into Android or iOS apps to provide address auto-completion for users in Brazil.
• Form Builders and Web Applications: Integrating with custom web forms or popular form builders to streamline user input for Brazilian addresses.

Alternatives

• Google Maps Platform: Offers global geocoding, reverse geocoding, and place autocomplete services, but operates on a paid model with a free tier and requires API key authentication for usage.
• LocationIQ: Provides global geocoding, reverse geocoding, and routing APIs, with a freemium model and clear documentation for developers.
• OpenCage Geocoder: A global geocoding API that aggregates data from open data sources, offering a freemium model and privacy-focused features.
• ArcGIS Platform: Provides a comprehensive suite of location services, including geocoding, routing, and spatial analysis, primarily aimed at enterprise and GIS professionals.

Getting started

Integrating ViaCep into your application is straightforward due to its RESTful design and lack of authentication. You can make a simple HTTP GET request to the API endpoint with the desired CEP.

Here's a JavaScript example demonstrating how to fetch address data for a Brazilian CEP (e.g., 01001000, which corresponds to Praça da Sé in São Paulo) using the fetch API:

async function getAddressByCep(cep) {
  try {
    const response = await fetch(`https://viacep.com.br/ws/${cep}/json/`);

    if (!response.ok) {
      if (response.status === 400) {
        throw new Error('Invalid CEP format (e.g., too short or non-numeric).');
      } else if (response.status === 404) {
        // ViaCEP returns 404 for valid formats but non-existent CEPs
        throw new Error('CEP not found or does not exist.');
      } else {
        throw new Error(`HTTP error! status: ${response.status}`);
      }
    }

    const data = await response.json();

    if (data.erro) {
      // ViaCEP returns { "erro": true } for validly formatted but non-existent CEPs
      throw new Error('CEP not found in ViaCEP database.');
    }

    console.log('Address details:', data);
    return data;
  } catch (error) {
    console.error('Error fetching address:', error.message);
    return null;
  }
}

// Example usage:
getAddressByCep('01001000'); // Valid CEP for Praça da Sé, São Paulo
getAddressByCep('99999999'); // Non-existent CEP
getAddressByCep('123');      // Invalid CEP format

This JavaScript code snippet defines an asynchronous function getAddressByCep that takes a CEP as an argument. It constructs the API URL, performs a fetch request, and then parses the JSON response. Error handling is included to catch network issues, invalid CEP formats, or CEPs that are not found in the ViaCep database. The data.erro property in the JSON response is a specific indicator from ViaCep that a validly formatted CEP could not be found. This example can be adapted for server-side environments using Node.js or integrated directly into front-end web applications. For detailed API usage and specific response fields, refer to the ViaCep API documentation.