CAMARA Population Density Data API - Follow-up meeting #6 - 2024-04-24

April 24th, 2024

Attendees

Population Density Data API minutes: https://wiki.camaraproject.org/display/CAM/Population+Density+Data+API+Minutes

Agenda

• Approval of previous meeting minutes #5 and meeting agenda
• Open issues and PRs
  
  • Issues: #6 #7 #10 #12 #13 #14 #15 #16 #20
  • PR #19 #21
• Initial algorithm proposal review
• Timeline and next steps
• AoB

Open Issues & PRs

Approval of previous meeting minutes & documentation (1)

Meeting Minutes #5

→ Approved

API proposal review (2)

Different discussions raised during the API review:

Issue#6 Information in water zones: Operators and therefore API can only provide data of those zones where it is operating. Full water or hybrid scenarios to be covered.

Status parameter is used for handling both situations:

• • Partial response, only some areas can be handled in the response. To discuss whether not-supported areas are to be included in the response.
  • Empty response, if no area is managed by operator and, therefore, no information can be provided.

Gregory/Tim: Include all the cells in the partial case, since the impact of including the empty cell is not big enough to lose the developer will expect as a full response.

• • • "noData" value to be added in those cells

Jorge: Calculating the cells, with no real value to developer, is costly for the CSP.

Decision: Move on with the most supported option. Empty cell in partial responses will be provided.

Issue #6 to be closed

Issue#7 Open discussion on default and limit values for the API characteristics:

• Default value on level 7 (150m x 150m) (TBC). Open Discussion, please provide feedback

Include input parameter where developer can chose among a list of levels. Also, to align on other global grid options in the future.

• • • 
      

      Option1: only support 6-7

• • • Option2: support any level, including a not-supported option. → Sachin, Tim, Jorge

Decision: Support a input parameter for the developer to select level (opt, default ==7), and create a "level nor supported" error. To consider in future release the analysis of other global grids.

• • • Maximum requested area size, need to consider a feasible maximum response size jointly with the maximum length of the timeframe. Dependency with Discussion on API spec - how to handle big areas/time in the response #10 Open Discussion, please provide feedback.

Let max area size open (technically) to a reasonable use case management, each operator can of course launch an error in case the size is not supported.

Issue to be closed after "bigger area than supported" error is included in the code

Issue#10

Following the discussion on maximum time frame and area to cover, we've been analyzing the management of valid/useful requests and the corresponding response. Considering the size of a common request, of 1 week and common areas of around 10Km2, the size of the response's content may be too big for being handled directly in the API REST body.

Proposal to analyse

Proposal is to analyze the implementation a unique asynchronous mechanisms for being able to handle both kind of scenarios, small scenarios where response will reach soon but also time and resource consuming scenarios where it may take even minutes to calculate the response.

→ to analyze limiting the size of the request to avoid complexity in the response, at least to consider response size that can fit properly in a HTTP response.

Decision: Support async endpoint for bigger and smaller areas, also needing to define a size limitation (area, duration and granularity) (TBD in issue #7). In any case, the response will be part of the API response body. Only identified limitation is on the calculation time, not in the response size.

Issue #10 to be closed 

Issue#13

Ericsson: Time format alignment with commonalities, supporting RFC instead of ISO

Decision: Agreed and solved in PR#21

Issue#14

Ericsson: Response content should follow the expected as in the API name, it is, density instead of population count

Decision: Analyze offline to make sure that API response is aligned with API name

• • • Or to change the API name to count
    • Or to change the response unit from people/cell to people/km2

AP: to define what max and min means in the calculated forecast. Also reconsider average as a forecast response, maybe just "expected"/"forecasted" population value

Issue#15

Ericsson: adding redoc and swagger editor links in API readme.

TEF: Mainly used in stable versions when a release is launched, in any case it's proposed in PR#19

Decision: Agreed and solved in PR#19

Issue#16

Orange: Align location area format with other APIs of CAMARA

Decision: Agreed and solved in PR#21

Issue#20

Orange: Proposal and alternative for implementation of async mechanism in the API response

Decision: 2 proposals of resolution:

• • Callback URL/ weebhook: More complex approach for the developer, but more suitable for unexpected response delays.
    • To include also a failure response for the callback in case the process cannot be completed.
    • Also to be included an error for the sync response
  • GET endpoint and requestID: easier to implement, more suitable for fast response APIs or APIs which response is expected in a specific delay. In longer responses, developer should poll the get endpoint.

Initial algorithm proposal (3)

Issue#12

Population Density API - Algorithm.pdf

→ To provide feedback

Discussion Summary

Next steps

1. Feedback on algorithm proposal→ Follow-up meeting #6
2. Feedback on the big responses management #6
3. RC API spec agreement → Follow-up meeting #7

• Next call will be May 8th, 2024