API response for summary view

[jeremiak]

Proposal for the API response and the data that we'll need as far as our current design goes:

{
  'address': '2964 E 3rd Street',
  'parcel_id': 'TF1234567890',
  'owner_information': {
    'name': 'Gina Sakich',
    'street_address': '5559 Little Debbie Parkway',
    'city': 'Chattanooga',
    'state': 'TN',
    'phone': '4443453434'
  }
  'utility_estimates': {
    'electricity': {
      'average_monthly_cost': 90
    },
    'water': {
      'average_monthly_cost': 35
    }
  },
  'code_violations': [
    {
      'description': 'Abandoned/inoperable vehicle',
      'date_issued': '09-12-2014'
      'current_status': 'outstanding'
    },
    {
      'description': 'Overgrowth on an unoccupied lot',
      'date_issued': '01-23-2010',
      'current_status': 'resolved'
    }
  ],
  'schools': {
    'elementary': 'Allen Elementary',
    'middle': 'East Ridge Middle',
    'high': 'East Ridge High'
  },
  'public_transit': ,
  'crime': ,
}

@jden & @GiselleS - I'm not sure we yet know exactly what data should come along with public_transit and crime but we can update that as those views are fleshed out.

Thoughts on if we should include more/different information?

[jeremiak]

Sam's TransitJSON inspired me to present the information as a flavor of GeoJSON to make it a bit more extensible. The id is meant to represent the parcel ID in this case.

{
  "type": "Feature",
  "properties": {
    "address": "2964E3rdStreet",
    "owner_information": {
      "name": "GinaSakich",
      "street_address": "5559LittleDebbieParkway",
      "city": "Chattanooga",
      "state": "TN",
      "phone": "4443453434"
    },
    "utility_estimates": {
      "electricity": {
        "average_monthly_cost": 90
      },
      "water": {
        "average_monthly_cost": 35
      }
    },
    "code_violations": [
      {
        "description": "Abandoned/inoperable vehicle",
        "date_issued": "09-12-2014",
        "current_status": "outstanding"
      },
      {
        "description": "Overgrowthonanunoccupiedlot",
        "date_issued": "01-23-2010",
        "current_status": "resolved"
      }
    ],
    "schools": {
      "elementary": "AllenElementary",
      "middle": "EastRidgeMiddle",
      "high": "EastRidgeHigh"
    },
    "public_transit": "",
    "crime": "lowest"
  },
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          100,
          0
        ],
        [
          101,
          0
        ],
        [
          101,
          1
        ],
        [
          100,
          1
        ],
        [
          100,
          0
        ]
      ]
    ]
  }
}

[junosuarez]

@jeremiak I'm +1 on returning GeoJSON, but I think it should be a Feature not a Polygon. Points and Polygons are primitive structures. Features / FeatureCollections are kind of the generic wrappers suitable for other things.

Also not sure if we should represent the parcel polygon or an address geocoded point as the primary geometry for a property. Additionally, we also have a building footprint, which would be another polygon.

Further, I think that the specific data sets should be removed a level, eg

Feature.properties.data.schools

rather than

Feature.properties.schools

This will let us enumerate over the datasets and make for a more flexible data model.

[jeremiak]

Awesome, 👍 for data as an element to contain all the data sets.

Isn't it a feature right now since the top-level type is Feature?

Maybe it should be a feature collection and then it can have three features:

1. Point for address
2. Parcel
3. Building footprint

The one thing I'm not clear about from reading the geojson spec is if the properties can be at the collection level to apply to every geometry underneath it, though geojson.io makes me think that properties can only be applied at the Feature level. Do you happen to know the answer to this?

The advantage of having all of that data in one collection would be that you can easily do different mapping applications beyond our original design and I'm not sure it really adds much overhead in terms of generation or weight of the response.

[jeremiak]

So @lyzidiamond proposed having a feature that has a geometrycollection with each of the three different features in it (reverse geocoded address, building footprint, parcel). This way the properties are maintained, but it seems like overkill to have all three items the more I think about it.

What is the benefit of having the reverse geocoded address? Easy mapping of points?

If we are choosing between building and parcel footprint, I would vote for building since the code violation data will pertain to a building and not a parcel. Also, the utility data is more closely linked to the building than the parcel (at least conceptually).

The downside of having all three in the collection would be that if you threw it on a map, it would draw three items per property which can get extremely cluttered pretty quick.

In short, I vote that each response is a Feature and we use the building footprint geometry as a polygon.

[junosuarez]

Isn't it a feature right now since the top-level type is Feature?

yes - I read it wrong.

The one thing I'm not clear about from reading the geojson spec is if the properties can be at the collection level to apply to every geometry underneath it, though geojson.io makes me think that properties can only be applied at the Feature level. Do you happen to know the answer to this?

Yes, additional properties can be added at any point in the object tree; GeoJSON just specifies minimum required properties. However, most tools are unlikely to read properties on a FeatureCollection and there is no guarantee of how they would be handled. The TransitJSON proposal has top level properties on a FeatureCollection to pertain to a transit agency.

How about returning a FeatureCollection with whatever geometries we have for the property as Features. All of the datasets and other fields related to the property would be under the properties part of the FeatureCollection. Further, an index between the type of Feature and the embedded Feature

[junosuarez]

from chat:

[17:30] jeremiak: we were doing the same thing apparently

[17:30] jden: ha

[17:30] jden: i'm thinking we don't even need to decide this yet

[17:31] jden: returning GeoJSON almost seems like a premature optimization

[17:31] jden: it'll be easy to have the API also support GeoJSON

[17:31] jden: but if we're not mapping the Summary screen, then I'm not sure why we're adding the complexity

[17:32] jden: on the search side, it would just be point based

[17:32] jden: eg no parcel polygons, building footprints, etc

[17:32] jeremiak: right re: search

[17:32] jeremiak: hmm

[17:33] jeremiak: i mean geojson seems to just make sense since it will make the API an easily implemented resource by itself

[17:33] jeremiak: but i'm down to put pause on the more detailed discussion of what that response looks like

[17:33] jeremiak: in terms of feature collection etc

[17:40] jden: it just seems like a lot of opportunity for bikeshedding.

[17:41] jeremiak: haha ok agreed

[junosuarez]

latest:

{
  'address': '2964 E 3rd Street',
  'parcel_id': 'TF1234567890',
  data: {
    'owner_information': {
      'name': 'Gina Sakich',
      'street_address': '5559 Little Debbie Parkway',
      'city': 'Chattanooga',
      'state': 'TN',
      'phone': '4443453434'
    }
    'utility_estimates': {
      'electricity': {
        'average_monthly_cost': 90
      },
      'water': {
        'average_monthly_cost': 35
      }
    },
    'code_violations': [
      {
        'description': 'Abandoned/inoperable vehicle',
        'date_issued': '09-12-2014'
        'current_status': 'outstanding'
      },
      {
        'description': 'Overgrowth on an unoccupied lot',
        'date_issued': '01-23-2010',
        'current_status': 'resolved'
      }
    ],
    'schools': {
      'elementary': 'Allen Elementary',
      'middle': 'East Ridge Middle',
      'high': 'East Ridge High'
    },
    'public_transit': ,
    'crime': ,  
  }

}

[junosuarez]

Can we switch to camelCase instead of inch_worm_case for variable names?

[junosuarez]

@jeremiak ping re above question

[jeremiak]

Yup, I'm totally fine with switching to camelCase for the variable names @jden

[junosuarez]

this is technically done:
http://rentfacts-api-dev.herokuapp.com/buildings/3

{
id: "3",
parcelId: "033024 00507",
address: "2622 YOUNG RD",
data: { }
}

Currently not returning anything in data because none of the other datasources are wired up. I'm gonna close this out though.