Getting started overview

Integrating with the Cep.la API involves a sequence of steps designed to quickly enable access to Brazilian postal code (CEP) data. The process begins with account creation, followed by the generation and retrieval of API credentials. Once credentials are secured, developers can construct and execute their initial API call to test connectivity and data retrieval. This guide outlines the necessary actions to move from account registration to a successful first API request, providing a foundation for further integration into applications requiring Brazilian address validation or lookup capabilities.

The Cep.la API is specifically designed for querying Brazilian postal codes, returning structured address data. It supports various use cases, including e-commerce shipping calculations and logistics services, by providing accurate and up-to-date address information. The documentation is provided in Portuguese, offering clear examples for integration. Users can access a free tier for up to 100 requests per day, with paid plans available for higher volumes.

Quick reference steps

The following table provides a high-level overview of the steps required to get started with Cep.la:

Step What to do Where
1. Create Account Register on the Cep.la website. Cep.la homepage
2. Get API Key Locate your unique API key in the dashboard. Cep.la dashboard (after login)
3. Make First Request Construct and execute a GET request to the API endpoint. Your preferred development environment (e.g., cURL, Postman, browser)
4. Parse Response Process the JSON data returned by the API. Your application logic

Create an account and get keys

To access the Cep.la API, you must first create an account on their official website. This account will serve as your primary interface for managing your API usage, monitoring request limits, and accessing your API key. The registration process typically involves providing an email address and setting a password.

  1. Navigate to the Cep.la Homepage: Open your web browser and go to the Cep.la website.
  2. Initiate Registration: Look for a 'Cadastre-se' (Sign Up) or 'Criar Conta' (Create Account) button. Click on it to begin the registration process.
  3. Provide Account Details: You will be prompted to enter your email address and create a password. Ensure you use a strong, unique password.
  4. Complete Verification: Follow any on-screen instructions for email verification, which may involve clicking a link sent to your registered email address.
  5. Log In to Your Dashboard: Once your account is verified, log in to the Cep.la dashboard using your new credentials.
  6. Locate Your API Key: Within the dashboard, there will be a section dedicated to API keys or credentials. Your unique API key will be displayed here. This key is crucial for authenticating your API requests. Keep it secure and do not expose it in client-side code or public repositories. The Cep.la documentation on API keys provides further details.

The API key acts as a token that identifies your application and authorizes your requests. It is a common method for API authentication, allowing the API provider to track usage and enforce rate limits for individual users or applications. Ensure you store your API key securely, preferably in environment variables or a secure configuration management system, rather than hardcoding it directly into your application's source code.

Your first request

After successfully obtaining your API key, you can proceed to make your first request to the Cep.la API. This initial call will verify your setup and demonstrate how to retrieve address data for a given Brazilian postal code.

API Endpoint

The primary endpoint for querying postal codes is:

GET https://cep.la/api/cep/{YOUR_CEP}

Replace {YOUR_CEP} with a valid 8-digit Brazilian postal code (e.g., 01001000 for São Paulo's central area).

Authentication

Your API key must be included in the request headers. The Cep.la API expects the key in an Authorization header with the prefix Token.

Authorization: Token YOUR_API_KEY

Replace YOUR_API_KEY with the actual key you obtained from your Cep.la dashboard.

Example Request (cURL)

Using cURL, a common command-line tool for making HTTP requests, you can construct your first call:

curl -X GET \
  -H "Authorization: Token YOUR_API_KEY" \
  https://cep.la/api/cep/01001000

Remember to substitute YOUR_API_KEY with your actual key.

Example Response

A successful request for a valid CEP will return a JSON object similar to this (exact fields may vary slightly depending on the data available for the specific CEP):

{
  "cep": "01001-000",
  "logradouro": "Praça da Sé",
  "complemento": "lado ímpar",
  "bairro": "Sé",
  "localidade": "São Paulo",
  "uf": "SP",
  "ibge": "3550308",
  "gia": "1004"
}

This response provides structured address information, including the street name (logradouro), neighborhood (bairro), city (localidade), and state (uf).

Testing in Browser

While direct browser access might not work due to the required Authorization header, you can use browser extensions like Postman or Insomnia, or a simple fetch request in a browser's developer console (for testing purposes, ensuring CORS is handled correctly if applicable) to test the API.

Common next steps

Once you have successfully made your first API call, you can proceed with further integration and optimization of your use of the Cep.la API:

  • Integrate into Your Application: Incorporate the API calls into your backend or frontend application logic. This might involve using a dedicated HTTP client library in your chosen programming language (e.g., requests in Python, axios in JavaScript, HttpClient in C#) to manage requests and parse responses.
  • Error Handling: Implement robust error handling. The API may return different HTTP status codes (e.g., 404 Not Found for invalid CEPs, 401 Unauthorized for invalid API keys, 429 Too Many Requests for rate limit breaches) and error messages. Your application should gracefully handle these scenarios to provide a good user experience and prevent unexpected crashes. The Cep.la documentation on error codes provides specific details.
  • Rate Limit Management: Be aware of the rate limits associated with your plan (100 requests/day for the free tier). Implement strategies such as request throttling or caching frequently accessed CEPs to stay within your limits and optimize performance.
  • Data Validation: Before sending a CEP to the API, validate its format (8 digits, numeric). This can reduce unnecessary API calls and improve the efficiency of your application.
  • Explore Advanced Features: Review the full Cep.la API documentation for any additional endpoints or parameters that might enhance your application's functionality, such as searching by address components if available, or understanding specific nuances of Brazilian address data.
  • Monitor Usage: Regularly check your Cep.la dashboard to monitor your API usage and ensure you are operating within your plan's limits.
  • Upgrade Plan: If your application's needs exceed the free tier, consider upgrading to a paid plan to accommodate higher request volumes. Paid plans start at R$ 29.90/month for 5,000 requests.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps for typical problems:

  • Incorrect API Key:
    • Symptom: HTTP 401 Unauthorized or 403 Forbidden status code.
    • Solution: Double-check that your API key is correctly copied from your Cep.la dashboard. Ensure there are no leading or trailing spaces. Verify that the Authorization header is correctly formatted as Token YOUR_API_KEY.
  • Invalid CEP Format:
    • Symptom: HTTP 400 Bad Request or 404 Not Found status code, or an error message indicating an invalid input.
    • Solution: Confirm the CEP is an 8-digit numeric string. Brazilian CEPs do not include hyphens when sent in the URL path, although they are often displayed with one (e.g., 01001000 instead of 01001-000).
  • Network Issues:
    • Symptom: Request timeouts, connection refused errors.
    • Solution: Check your internet connection. If you are behind a corporate firewall or proxy, ensure it is configured to allow outbound connections to https://cep.la.
  • Rate Limit Exceeded:
    • Symptom: HTTP 429 Too Many Requests status code.
    • Solution: If you are on the free tier, you are limited to 100 requests per day. Wait for the limit to reset or consider upgrading your plan. Ensure your testing strategy doesn't rapidly exhaust your quota.
  • Incorrect Endpoint URL:
    • Symptom: HTTP 404 Not Found status code from the server, or a DNS resolution error.
    • Solution: Verify that the base URL (https://cep.la/api/cep/) is correct and that the CEP is appended properly. Refer to the Cep.la API documentation for the exact endpoint structure.
  • CORS Issues (for browser-based requests):
    • Symptom: Browser console errors related to Cross-Origin Resource Sharing.
    • Solution: The Cep.la API is designed for server-side integration. If you are attempting to call it directly from a browser, you might encounter CORS restrictions. For production applications, it's recommended to make API calls from your backend server to avoid CORS issues and protect your API key. If testing directly from a browser for development, you might need to use a proxy or a browser extension that bypasses CORS for local development, though this is not suitable for production.

For more detailed information and specific error codes, always consult the official Cep.la documentation.