Initial import

1 files changed, 289 insertions, 0 deletions

diff --git a/src/cepis_models.f90 b/src/cepis_models.f90
new file mode 100644
index 0000000..c50d206
--- /dev/null
+++ b/src/cepis_models.f90
@@ -0,0 +1,289 @@
+!> The data the API returns, as derived types.
+!>
+!> **Field names are the API's own, in Portuguese** — `logradouro`, `bairro`,
+!> `localidade`. Everything else in this library is English; the fields are the
+!> one deliberate exception.
+!>
+!> The reason is fidelity: what you read in the JSON at
+!> https://cep.is/01001000 is exactly what you access on the derived type.
+!> Translating to `street`/`city` would mean maintaining a field-by-field
+!> mapping and forcing anyone reading the API docs alongside this library to
+!> translate back in their head. The values are Portuguese either way — they
+!> come from the Correios database.
+module cepis_models
+    use, intrinsic :: iso_fortran_env, only: real64, int64
+    use cepis_json, only: json_document, JSON_NUMBER, JSON_STRING, JSON_OBJECT
+    use cepis_strings, only: parse_real, is_digits
+    implicit none
+    private
+
+    public :: cepis_geo
+    public :: cepis_address
+    public :: cepis_health
+    public :: address_clear
+    public :: address_from_json
+    public :: health_from_json
+    public :: cepis_format_cep
+
+    !> The CEP's coordinate, when the database has one.
+    !>
+    !> The point is the **median** of the coordinates of that CEP's addresses,
+    !> not the mean: one badly geocoded address 40 km away shifts a mean and
+    !> does not move a median.
+    !>
+    !> Always check `precisao` before using `lat`/`lon` for distance:
+    !>
+    !> - `"logradouro"`: the point is a stretch of street. `raio_m` lands
+    !>   around 100-150 m. Good for maps and for distance.
+    !> - `"localidade"`: the CEP *is* the whole municipality (a city-wide
+    !>   general CEP) and the point is its centroid. `raio_m` runs from 7 km to
+    !>   40 km. Computing shipping from this is wrong by tens of kilometres.
+    !>
+    !> `raio_m` is the radius containing 90% of that CEP's addresses. It exists
+    !> precisely so that error cannot pass unnoticed.
+    type :: cepis_geo
+        !> Latitude in decimal degrees.
+        real(real64) :: lat = 0.0_real64
+        !> Longitude in decimal degrees.
+        real(real64) :: lon = 0.0_real64
+        !> Radius in metres containing 90% of the CEP's addresses.
+        integer :: raio_m = 0
+        !> `"logradouro"` or `"localidade"`.
+        character(len=:), allocatable :: precisao
+    contains
+        !> `.true.` when the coordinate points at a street, not a
+        !> municipality. Shorthand for `precisao == 'logradouro'`, which is the
+        !> check to make before using the point to measure distance.
+        procedure :: is_precise
+    end type cepis_geo
+
+    !> A CEP and everything the database knows about it.
+    !>
+    !> Every character component is allocated after any successful call. Fields
+    !> the database does not have for that CEP are the empty string, never
+    !> unallocated — that is what the API returns, and changing it here would
+    !> create a difference between reading the JSON and reading this library.
+    !>
+    !> `geo` is the exception, and it is guarded by `has_geo` rather than by an
+    !> unallocated component: the API **omits** the whole field when there is
+    !> no coordinate (about 43% of CEPs) rather than sending null, and a flag
+    !> makes the check impossible to forget.
+    type :: cepis_address
+        !> `.false.` for a CEP that the batch did not resolve. Always `.true.`
+        !> for an address that came back from a single lookup.
+        logical :: found = .false.
+        !> The 8 digits, unmasked.
+        character(len=:), allocatable :: cep
+        character(len=:), allocatable :: logradouro
+        character(len=:), allocatable :: complemento
+        character(len=:), allocatable :: unidade
+        character(len=:), allocatable :: bairro
+        character(len=:), allocatable :: localidade
+        !> Two-letter state code, e.g. `SP`.
+        character(len=:), allocatable :: uf
+        character(len=:), allocatable :: estado
+        character(len=:), allocatable :: regiao
+        !> IBGE municipality code.
+        character(len=:), allocatable :: ibge
+        character(len=:), allocatable :: gia
+        character(len=:), allocatable :: ddd
+        character(len=:), allocatable :: siafi
+        !> `.true.` when `geo` carries a coordinate.
+        logical :: has_geo = .false.
+        !> The coordinate. Meaningful only when `has_geo` is `.true.`.
+        type(cepis_geo) :: geo
+        !> The response body exactly as it arrived, uninterpreted, so a field
+        !> the API grows before this library is updated is not lost. Empty for
+        !> addresses that came from a batch, whose transport is CSV.
+        character(len=:), allocatable :: raw
+    contains
+        !> The CEP with its mask: `01001-000`. Empty when `cep` is not 8
+        !> digits.
+        procedure :: formatted_cep
+    end type cepis_address
+
+    !> The response of `GET /health`.
+    !>
+    !> Good for two things: checking that the API answers, and knowing **which
+    !> version of the database** is live. The DNE database changes every two
+    !> weeks; `dne` identifies it.
+    type :: cepis_health
+        !> `ok` when the API reports itself healthy.
+        character(len=:), allocatable :: status
+        !> Identifier of the fortnightly DNE database.
+        character(len=:), allocatable :: dne
+        !> CEPs in the database.
+        integer(int64) :: ceps = 0_int64
+        !> CEPs that carry a coordinate.
+        integer(int64) :: geo = 0_int64
+        !> ISO-8601 timestamp of the database build.
+        character(len=:), allocatable :: base_gerada_em
+    contains
+        !> `.true.` when the API reports itself healthy.
+        procedure :: ok => health_ok
+    end type cepis_health
+
+contains
+
+    pure function is_precise(self) result(yes)
+        class(cepis_geo), intent(in) :: self
+        logical :: yes
+
+        yes = .false.
+        if (allocated(self%precisao)) yes = self%precisao == 'logradouro'
+    end function is_precise
+
+    pure function health_ok(self) result(yes)
+        class(cepis_health), intent(in) :: self
+        logical :: yes
+
+        yes = .false.
+        if (allocated(self%status)) yes = self%status == 'ok'
+    end function health_ok
+
+    pure function formatted_cep(self) result(text)
+        class(cepis_address), intent(in) :: self
+        character(len=:), allocatable :: text
+
+        text = ''
+        if (.not. allocated(self%cep)) return
+        text = cepis_format_cep(self%cep)
+    end function formatted_cep
+
+    !> Write the CEP with its mask: `01001-000`.
+    !>
+    !> The native contract always returns it unmasked; formatting is
+    !> presentation, and it lives here so it does not become a repeated
+    !> `write` in every project that uses this. Empty for anything that is not
+    !> 8 digits.
+    pure function cepis_format_cep(cep) result(text)
+        character(len=*), intent(in) :: cep
+        character(len=:), allocatable :: text
+
+        text = ''
+        if (len(cep) /= 8) return
+        if (.not. is_digits(cep)) return
+        text = cep(1:5)//'-'//cep(6:8)
+    end function cepis_format_cep
+
+    !> Reset an address to empty strings and no coordinate.
+    !>
+    !> Every character component ends up allocated, so a caller can read any of
+    !> them without checking `allocated` first.
+    pure subroutine address_clear(address)
+        type(cepis_address), intent(out) :: address
+
+        address%found = .false.
+        address%cep = ''
+        address%logradouro = ''
+        address%complemento = ''
+        address%unidade = ''
+        address%bairro = ''
+        address%localidade = ''
+        address%uf = ''
+        address%estado = ''
+        address%regiao = ''
+        address%ibge = ''
+        address%gia = ''
+        address%ddd = ''
+        address%siafi = ''
+        address%has_geo = .false.
+        address%raw = ''
+    end subroutine address_clear
+
+    !> Build an address from a parsed JSON object.
+    !>
+    !> Unknown fields are ignored but preserved in `raw`, so a new field in the
+    !> API cannot break this library. A malformed `geo` block yields
+    !> `has_geo = .false.` rather than a failure: it is not worth losing the
+    !> whole address over, since the rest of the response is still useful.
+    subroutine address_from_json(doc, node, raw, address)
+        type(json_document), intent(in) :: doc
+        integer, intent(in) :: node
+        character(len=*), intent(in) :: raw
+        type(cepis_address), intent(out) :: address
+
+        call address_clear(address)
+        address%found = .true.
+        address%raw = raw
+
+        address%cep = doc%field_text(node, 'cep')
+        address%logradouro = doc%field_text(node, 'logradouro')
+        address%complemento = doc%field_text(node, 'complemento')
+        address%unidade = doc%field_text(node, 'unidade')
+        address%bairro = doc%field_text(node, 'bairro')
+        address%localidade = doc%field_text(node, 'localidade')
+        address%uf = doc%field_text(node, 'uf')
+        address%estado = doc%field_text(node, 'estado')
+        address%regiao = doc%field_text(node, 'regiao')
+        address%ibge = doc%field_text(node, 'ibge')
+        address%gia = doc%field_text(node, 'gia')
+        address%ddd = doc%field_text(node, 'ddd')
+        address%siafi = doc%field_text(node, 'siafi')
+
+        call read_geo(doc, doc%member(node, 'geo'), address)
+    end subroutine address_from_json
+
+    subroutine read_geo(doc, node, address)
+        type(json_document), intent(in) :: doc
+        integer, intent(in) :: node
+        type(cepis_address), intent(inout) :: address
+        real(real64) :: lat, lon, radius
+        logical :: ok
+        character(len=:), allocatable :: precisao
+
+        address%has_geo = .false.
+        if (doc%kind_of(node) /= JSON_OBJECT) return
+
+        call number_field(doc, node, 'lat', lat, ok)
+        if (.not. ok) return
+        call number_field(doc, node, 'lon', lon, ok)
+        if (.not. ok) return
+        call number_field(doc, node, 'raio_m', radius, ok)
+        if (.not. ok) return
+
+        if (doc%kind_of(doc%member(node, 'precisao')) /= JSON_STRING) return
+        precisao = doc%field_text(node, 'precisao')
+
+        address%geo%lat = lat
+        address%geo%lon = lon
+        address%geo%raio_m = int(radius)
+        address%geo%precisao = precisao
+        address%has_geo = .true.
+    end subroutine read_geo
+
+    subroutine number_field(doc, node, name, value, ok)
+        type(json_document), intent(in) :: doc
+        integer, intent(in) :: node
+        character(len=*), intent(in) :: name
+        real(real64), intent(out) :: value
+        logical, intent(out) :: ok
+        integer :: child
+
+        value = 0.0_real64
+        ok = .false.
+        child = doc%member(node, name)
+
+        select case (doc%kind_of(child))
+        case (JSON_NUMBER)
+            value = doc%number_of(child)
+            ok = .true.
+        case (JSON_STRING)
+            call parse_real(doc%text_of(child), value, ok)
+        end select
+    end subroutine number_field
+
+    !> Build a health report from a parsed JSON object.
+    subroutine health_from_json(doc, node, health)
+        type(json_document), intent(in) :: doc
+        integer, intent(in) :: node
+        type(cepis_health), intent(out) :: health
+
+        health%status = doc%field_text(node, 'status')
+        health%dne = doc%field_text(node, 'dne')
+        health%ceps = doc%field_integer(node, 'ceps')
+        health%geo = doc%field_integer(node, 'geo')
+        health%base_gerada_em = doc%field_text(node, 'base_gerada_em')
+    end subroutine health_from_json
+
+end module cepis_models