Structure admin area endpoints

[olafveerman]

Triggered by Derek's question in orma/openroads-analytics#52, I think there is some room for improvement on the endpoints that deal with administrative areas, especially on how we structure the routes.

Here's a proposal that aims for two things:

• makes it easy to get data from either a particular admin area or its descendants
• provides high degree of control over what data is returned

Single administrative areas

Get information from a single administrative area. Does not include a reference to its descendants.

endpoint	returns
/admin/:id	Basic meta-data (name, id, type)
/admin/:id/boundary	Basic meta-data + Boundary
/admin/:id/road-network	Basic meta-data + Road network

Subregions

Get data from the subregions of a given area.

endpoint	returns
/admin/:id/subregions	Basic meta-data of all sub-regions (name, id, type)
/admin/:id/subregions/boundary	Basic metadata + boundary of subregions

@dereklieu @kamicut @anandthakker @danielfdsilva
Would be great to hear your thoughts. Whether you agree that there is a need to begin with, the proposed structure, etc. This could be tackled first thing in phase 2.
Let me know if you want me to illustrate it with examples from the response.

[olafveerman]

BTW I can even imagine we don't need /admin/:id/road-network at all and use what's now the /map endpoint.

[danielfdsilva]

It helps to understand how the api is structured and what's the relation between the different elements.
If the changes are easy to perform I say go for it.

[anandthakker]

A big 👍 from me!

@olafveerman Not sure about /map replacing /admin/:id/road-network, since the latter is meant to clip the roads to the boundary of the region, whereas the former returns the entirety of any way that intersects the requested bbox. (Unless something's changed about the map endpoint.)

[olafveerman]

Ah, good point. Will also include that in the documentation, thanks @anandthakker

[dereklieu]

Yeah, I also think this is a good list to start with on Phase 2. It'd be nice to have the flexibility as we flesh out these analytics pages more.

[danielfdsilva]

Had a look at the current endpoints and how the data is structured. Here's a proposal for what the data could look like for the new endpoints:

/admin/:id (Basic meta-data (name, id, type))

{
    "id": ​2110147000,
    "adminType": ​3,
    "name": "Basco",
    "properties":  {
        "ID_0": ​177,
        "ISO": "PHL",
        "NAME_0": "Philippines",
        "ID_2_OR": ​2110000000,
        "NAME_2": "Batanes",
        "ID_3_OR": ​2110147000,
        "NAME_3": "Basco",
        "NL_NAME_3": null,
        "VARNAME_3": null,
        "TYPE_3": "Bayan|Munisipyo",
        "ENGTYPE_2": "Municipality",
        "X_COORD": ​121.99262517700001,
        "Y_COORD": ​20.458421853399997
    }
}

/admin/:id/boundary (Basic meta-data + Boundary)

{
  "type": "Feature",
  "properties": {
    "ID_0": 177,
    "ISO": "PHL",
    "NAME_0": "Philippines",
    "ID_2_OR": 2110000000,
    "NAME_2": "Batanes",
    "ID_3_OR": 2110147000,
    "NAME_3": "Basco",
    "NL_NAME_3": null,
    "VARNAME_3": null,
    "TYPE_3": "Bayan|Munisipyo",
    "ENGTYPE_2": "Municipality",
    "X_COORD": 121.99262517700001,
    "Y_COORD": 20.458421853399997
  },
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          122.00363922119175,
          20.489030838012688
        ]
        // More Coords
      ]
    ]
  },
  "id": 2110147000,
  "adminType": 3,
  "name": "Basco"
}

/admin/:id/road-network (Basic meta-data + Road network)

{
"id": ​2110147000,
"adminType": ​3,
"name": "Basco",
"roads": {
    "type": "FeatureCollection",
    "features": [ /* no features for this region */ ]
  }
}

Thoughts? Is this what you had in mind?
Something that is kind of bothering me is that the responses vary between json (1st and 3rd) and geojson (2nd). Do you see this as a consistency problem or is it my ocd kicking in? :P

@dereklieu You thinks it's enough to omit the properties we don't want from the response or should we change the db queries and do not return them in the first place? What kind of implications does this have?

[dereklieu]

@danielfdsilva do you mean all the nulls for NL_NAME_3 and so forth? I don't see any harm in keeping them there, and it keeps the response structure consistent for every admin level, which would be helpful if you're new to using this part of the API.

As for the json/geojson schism, I hadn't thought of it but it's a little strange now that you bring it up. I guess I wouldn't mind turning the road-network into geojson format, but since the base admin endpoint is about the metadata, I'm fine keeping that as json.

[dereklieu]

@danielfdsilva and I'd have to check but I'm pretty sure making any changes here will break the dashboards, to some degree. So we should look into that and do the appropriate changes before we push these live.

[danielfdsilva]

@dereklieu Actually I meant something different.
For the first response (/admin/:id) we're not returning the geometry, but the function getAdminBoundary(id) returns it. My question was do we create another function that returns just what we're looking for, or is it enough to omit what we don't want (like geometry) from the result before sending it to the client.

The roads object in the road-network is a geojson, but is not at root level...

These changes are going to break the dashboards. Before pushing this we need to make changes to the dashboards as well.

[dereklieu]

@danielfdsilva sorry, not sure I understand the question here. What are we looking for here? Is it that we're doing an unnecessary calculation of geometry without using it?

And yes, the roads is not currently geojson at root level. If we wanted to standardize on geojson we could just attach id, adminType, and name as properties.

Yes, these changes will break the dashboards. The easiest way would be, once you're at a stage where you feel good about the refactor, push these changes up to a branch so we can figure out what's different, then modify the dashboards accordingly.

[danielfdsilva]

Document with the current status / some points to consider:

https://gist.github.com/danielfdsilva/29156361658a921eabb4

[olafveerman]

• What is NL_NAME_3 and VARNAME_3?

I think we can remove them, but I'll double check that tomorrow morning

• What are ENGTYPE_2 and TYPE_3 used for? And Why one is _2 and the other _3 even though it looks like the refer to the same?

The third administrative level is usually a Municipality, but can also be a City. My guess is that TYPE_3 is the Philippine term and ENGTYPE_3 is the English translation. Again, will check tomorrow.

• Since this endoint is specific for boundaries and we're not returning them, should we return an error instead?

Yes, but in principle we should always return a boundary on the boundary endpoints.

Could we simplify the /admin/:id/subregions endpoint to something like:

{
  "id": 13000000000,
  "name": "Region IV-B (Mimaropa)",
  "properties": {
    "NAME_0": "Philippines"
  },
  "adminAreas": [
    {
      "id": "13020000000",
      "name": "Agusan Del Norte",
      "X_COORD": 118.46191032700001,
      "Y_COORD": 9.50722963322
    },
   {}
  ]
}

Each adminArea doesn't need a sub-object with properties, since they will always be the same as their parent.

[danielfdsilva]

The adminAreas don't need a sub-object with properties, since they will always be the same as their parent.

Yes, valid point. We could event remove it for the parent and standardize. We'd only leave it when the response is geojson