Enhancing Brazilian Address Formatting

[djedu28]

Original Text in Portuguese Brazil

## Melhoria no endereçamento brasileiro.

O endereço no Brasil possui os seguintes elementos (marcado onde a implementação atual contempla)

• - Indicador de rua, avenida ou travessa
• - Logradouro - É o nome da rua, avenida, praça ou outro tipo de via pública onde o imóvel está localizado.
• - Número do endereço - Indica o número do imóvel dentro do logradouro.
• - Complemento de endereço, se houver.
  • Informação adicional que ajuda a localizar o imóvel dentro do terreno, como apartamento, bloco, casa, etc.
• - Nome do bairro
• - Cidade e UF do estado
• - CEP correto

faltando somente atender o complemento

A linha do complemento é formado por identificador de quadra, bloco, anexo, ..., ou um ponto de referência para localizar o imóvel.

O complemento é incluindo antes do bairro e depois da informação da rua, numero.

• exemplo de complemento:
  • apartamento 201
  • bloco 10, apartamento 201
  • Quadra 7
  • Anexo D
  • Casa F
  • Fundos
  • Sobrado

Para continuar mantendo compatibilidade com o padrão da api atual

Uma solução (rápida) pode ser feita a nível do template:

• incluir o {{{quarter}}}, que representaria o "complemento" do endereço (já que o quarter faz parte do complemento, e das variáveis é a única que se aproxima do conceito de complemento)

---

Existem 3 possibilidades para Adicionar o Complemento

1. Criar uma nova variável:

   • Vantagem: Permite um controle total sobre a posição e o formato do complemento.
   • Desvantagem: Requer mais customização e pode tornar a template mais complexa.

2. Utilizar uma variável existente:

   • Vantagem: Pode ser mais simples, especialmente se houver uma variável que já contém informações semelhantes.
   • Desvantagem: Pode limitar a flexibilidade na formatação.

3. Combinar ambas as opções:

   • Vantagem: Permite um equilíbrio entre flexibilidade e simplicidade.
   • Desvantagem: Pode exigir um pouco mais de trabalho inicial.

---

Exemplo Prático

1. Adicionando uma variável {{{address_complement}}} ou {{{complement}}}
   Onde, complement contém o complemento do endereço (Apt. 201, Bloco B, etc.).
   o template ficaria assim:
   address-formatting/conf/countries/worldwide.yaml#L439C1-L451C1

   # Brazil
   BR:
       address_template: |
           {{{attention}}}
           {{{house}}}
   -       {{{road}}} {{{house_number}}}
   +       {{{road}}} {{{house_number}}} {{{complement}}}
           {{#first}} {{{suburb}}} || {{{city_district}}} || {{{village}}} || {{{hamlet}}}{{/first}}
           {{#first}} {{{city}}} || {{{town}}} || {{{state_district}}} {{/first}} - {{#first}} {{{state_code}}} || {{{state}}} {{/first}}
           {{{postcode}}}
           {{{country}}}
       postformat_replace:
           - ["\\b(\\d{5})(\\d{3})\\b","$1-$2"]

   Com a adição de complement, é necessário mapear a nova variável para não cair em {{{attention}}}

   address-formatting/conf/components.yaml#L101

   ...
   ---
   name: continent
   + ---
   + name: complement

2. Utilizar uma variável existente.
   Comentado no tópico anterior, poderemos utilizar o {{{quarter}}}.
   o template ficaria assim:
   address-formatting/conf/countries/worldwide.yaml#L439C1-L451C1

   # Brazil
   BR:
       address_template: |
           {{{attention}}}
           {{{house}}}
   -       {{{road}}} {{{house_number}}}
   +       {{{road}}} {{{house_number}}} {{{quarter}}}
           {{#first}} {{{suburb}}} || {{{city_district}}} || {{{village}}} || {{{hamlet}}}{{/first}}
           {{#first}} {{{city}}} || {{{town}}} || {{{state_district}}} {{/first}} - {{#first}} {{{state_code}}} || {{{state}}} {{/first}}
           {{{postcode}}}
           {{{country}}}
       postformat_replace:
           - ["\\b(\\d{5})(\\d{3})\\b","$1-$2"]
   

3. Combinar ambas as opções:
   address-formatting/conf/countries/worldwide.yaml#L439C1-L451C1

   # Brazil
   BR:
       address_template: |
           {{{attention}}}
           {{{house}}}
   -       {{{road}}} {{{house_number}}}
   +       {{{road}}} {{{house_number}}} {{#first}} , {{{quarter}}}, {{{complement}}} || , {{{complement}}}{{/first}}
           {{#first}} {{{suburb}}} || {{{city_district}}} || {{{village}}} || {{{hamlet}}}{{/first}}
           {{#first}} {{{city}}} || {{{town}}} || {{{state_district}}} {{/first}} - {{#first}} {{{state_code}}} || {{{state}}} {{/first}}
           {{{postcode}}}
           {{{country}}}
       postformat_replace:
           - ["\\b(\\d{5})(\\d{3})\\b","$1-$2"]
   

   address-formatting/conf/components.yaml#L101

   ...
   ---
   name: continent
   + ---
   + name: complement
   + aliases:
   +     - quarter 

Improving Brazilian Address Formatting

Brazilian addresses typically include the following components (marked where the current implementation supports them):

• - Street type (e.g., street, avenue, lane)
• - Street name
• - House number
• - Address complement (if applicable)
  • Additional information to pinpoint the exact location within a property, such as apartment number, block, house, etc.
• - Neighborhood
• - City and state
• - CEP code

Missing: Address Complement

The address complement can include a block identifier, annex, or other reference point to locate the property.

The complement should be placed before the neighborhood and after the street name and number.

• Examples of complements:
  • apartamento 201
  • bloco 10, apartamento 201
  • Quadra 7
  • Anexo D
  • Casa F
  • Fundos
  • Sobrado

Maintaining Compatibility with the Current API

A quick solution could be implemented at the template level:

• Introduce {{{quarter}}} to represent the address complement (since "quarter" is part of the complement and is the closest existing variable).

---

Three Approaches to Add the Complement

1. Create a new variable:

   • Advantage: Provides full control over the complement's position and format.
   • Disadvantage: Requires more customization and can complicate the template.

2. Utilize an existing variable:

   • Advantage: Simpler, especially if a similar variable already exists.
   • Disadvantage: May limit formatting flexibility.

3. Combine both options:

   • Advantage: Balances flexibility and simplicity.
   • Disadvantage: Requires more initial setup.

---

Practical Example

1. Adding a new variable {{{address_complement}}} or {{{complement}}}:
   Where complement contains the address complement (Apt. 201, Block B, etc.).
   The template would look like this:
   address-formatting/conf/countries/worldwide.yaml#L439C1-L451C1

   # Brazil
   BR:
       address_template: |
           {{{attention}}}
           {{{house}}}
   -       {{{road}}} {{{house_number}}}
   +       {{{road}}} {{{house_number}}} {{{complement}}}
           {{#first}} {{{suburb}}} || {{{city_district}}} || {{{village}}} || {{{hamlet}}}{{/first}}
           {{#first}} {{{city}}} || {{{town}}} || {{{state_district}}} {{/first}} - {{#first}} {{{state_code}}} || {{{state}}} {{/first}}
           {{{postcode}}}
           {{{country}}}
       postformat_replace:
           - ["\\b(\\d{5})(\\d{3})\\b","$1-$2"]

   With the addition of complement, it is necessary to map the new variable so as not to fall to {{{attention}}}

   address-formatting/conf/components.yaml#L101

   ...
   ---
   name: continent
   + ---
   + name: complement

2. Using an existing variable:
   As mentioned earlier, we could use {{{quarter}}}.
   The template would look like this:
   address-formatting/conf/countries/worldwide.yaml#L439C1-L451C1

   # Brazil
   BR:
       address_template: |
           {{{attention}}}
           {{{house}}}
   -       {{{road}}} {{{house_number}}}
   +       {{{road}}} {{{house_number}}} {{{quarter}}}
           {{#first}} {{{suburb}}} || {{{city_district}}} || {{{village}}} || {{{hamlet}}}{{/first}}
           {{#first}} {{{city}}} || {{{town}}} || {{{state_district}}} {{/first}} - {{#first}} {{{state_code}}} || {{{state}}} {{/first}}
           {{{postcode}}}
           {{{country}}}
       postformat_replace:
           - ["\\b(\\d{5})(\\d{3})\\b","$1-$2"]
   

3. Combining both options:
   address-formatting/conf/countries/worldwide.yaml#L439C1-L451C1

   # Brazil
   BR:
       address_template: |
           {{{attention}}}
           {{{house}}}
   -       {{{road}}} {{{house_number}}}
   +       {{{road}}} {{{house_number}}} {{#first}} , {{{quarter}}}, {{{complement}}} || , {{{complement}}}{{/first}}
           {{#first}} {{{suburb}}} || {{{city_district}}} || {{{village}}} || {{{hamlet}}}{{/first}}
           {{#first}} {{{city}}} || {{{town}}} || {{{state_district}}} {{/first}} - {{#first}} {{{state_code}}} || {{{state}}} {{/first}}
           {{{postcode}}}
           {{{country}}}
       postformat_replace:
           - ["\\b(\\d{5})(\\d{3})\\b","$1-$2"]
   

   address-formatting/conf/components.yaml#L101

   ...
   ---
   name: continent
   + ---
   + name: complement
   + aliases:
   +     - quarter 

[freyfogle]

Obrigado!

Due to Christmas break it will take a few days to review this

[djedu28]

Obrigado!

Due to Christmas break it will take a few days to review this

Merry Christmas and happy holidays!

Thank you for your quick reply.

No rush, I've been playing around with this and tested it out by modifying node_modules/@fragaria/address-formatter/dist/cjs/address-formatter.js.

Option 3 didn't cause any unexpected errors with old addresses. I just need to understand the policy for adding a new variable, if it's possible.

I'll write some tests for the new format and submit a PR for option 3 soon.

**Original Text in Portuguese Brazil**

Feliz natal, e bom descanso.

Agradeço pela rápida resposta.

Não tenha pressa, eu já fiz alguns testes enquanto escrevia a issue. Modificando e testando no arquivo node_modules/@fragaria/address-formatter/dist/cjs/address-formatter.js

A opção 3 não causou erros inesperados com endereços antigos, resta só entender a política para inserir uma nova variável, se é que isso é possível.

Mais tarde irei escrever alguns testes para o novo formato e enviar a opção 3 para revisão em uma Pull request

[djedu28]

PS: All content was prepared by me. Artificial intelligence was used only as a translation tool.