A Brazilian ZIP code (CEP) lookup library for Dart and Flutter applications. This package provides easy access to Brazilian postal code information using the ViaCEP API.
- ✅ Easy to use: Simple API for ZIP code lookup
- ✅ Multiple formats: Support for formatted (01310-100) and unformatted (01310100) ZIP codes
- ✅ Output formats: JSON and XML response formats
- ✅ Error handling: Comprehensive error handling with custom exceptions
- ✅ Null safety: Full null safety support
- ✅ Well tested: Comprehensive test coverage
- ✅ Platform support: Works on Android, iOS, Web, Windows, macOS, and Linux
- ✅ Documentation: Full API documentation
Add this to your package's pubspec.yaml file:
dependencies:
flutter_cep2: ^1.0.0Then run:
dart pub getimport 'package:flutter_cep2/flutter_cep2.dart';import 'package:flutter_cep2/flutter_cep2.dart';
Future<void> main() async {
final cepService = FlutterCep2();
try {
final result = await cepService.search('01310-100');
print('CEP: ${result.cep}');
print('Address: ${result.logradouro}');
print('Neighborhood: ${result.bairro}');
print('City: ${result.localidade}');
print('State: ${result.uf}');
} catch (e) {
print('Error: $e');
}
// Don't forget to dispose
cepService.dispose();
}The library accepts ZIP codes in various formats:
final cepService = FlutterCep2();
// All of these work:
await cepService.search('01310-100'); // Formatted
await cepService.search('01310100'); // Unformatted
await cepService.search('01.310-100'); // Alternative formattingfinal result = await cepService.search(
'01310-100',
output: CepOutputFormat.xml,
);try {
final result = await cepService.search('00000-000');
} on CepException catch (e) {
print('CEP Error: ${e.message}');
} catch (e) {
print('Other error: $e');
}Main service class for ZIP code operations.
FlutterCep2({http.Client? client})- Creates a new instance. Optionally accepts a custom HTTP client for testing.
Future<Cep> search(String cep, {CepOutputFormat output = CepOutputFormat.json})- Searches for ZIP code informationvoid dispose()- Closes the HTTP client
Model class representing Brazilian ZIP code information.
String cep- The ZIP code in format XXXXX-XXXString logradouro- Street nameString? complemento- Additional address informationString bairro- NeighborhoodString localidade- City nameString uf- State abbreviationString? unidade- Postal unitString ibge- IBGE city codeString? gia- GIA code (São Paulo only)String? ddd- Area codeString? siaf- SIAF code
Enum for output format options.
CepOutputFormat.json- JSON format (default)CepOutputFormat.xml- XML format
Exception thrown when there's an error with ZIP code operations.
String message- The error message
import 'package:flutter/material.dart';
import 'package:flutter_cep2/flutter_cep2.dart';
class CepLookupWidget extends StatefulWidget {
@override
_CepLookupWidgetState createState() => _CepLookupWidgetState();
}
class _CepLookupWidgetState extends State<CepLookupWidget> {
final _cepService = FlutterCep2();
final _controller = TextEditingController();
Cep? _result;
String? _error;
@override
void dispose() {
_cepService.dispose();
_controller.dispose();
super.dispose();
}
Future<void> _searchCep() async {
setState(() {
_result = null;
_error = null;
});
try {
final result = await _cepService.search(_controller.text);
setState(() {
_result = result;
});
} on CepException catch (e) {
setState(() {
_error = e.message;
});
}
}
@override
Widget build(BuildContext context) {
return Column(
children: [
TextField(
controller: _controller,
decoration: InputDecoration(
labelText: 'Enter CEP',
suffixIcon: IconButton(
icon: Icon(Icons.search),
onPressed: _searchCep,
),
),
),
if (_result != null) ...[
Text('Address: ${_result!.logradouro}'),
Text('City: ${_result!.localidade} - ${_result!.uf}'),
],
if (_error != null)
Text('Error: $_error', style: TextStyle(color: Colors.red)),
],
);
}
}The package includes comprehensive tests. To run them:
dart testContributions are welcome! Please feel free to submit a Pull Request.
See CHANGELOG.md for a detailed list of changes.
This project is licensed under the MIT License - see the LICENSE file for details.
- Uses the ViaCEP API for ZIP code data
- Maintained by Vitor Amaral
If you have any issues or questions, please file them in the issue tracker.
Made with ❤️ in Brazil 🇧🇷