mdb / node-phli

A Node.js module for interacting with the City of Philadelphia's Licenses & Inspections data.

phli

A Node.js module for interacting with the City of Philadelphia's Licenses & Inspections data.

phli was built during the December 2012 Random Hacks of Kindness Philadelphia hackathon.

Getting Started

Install phli:

npm install phli

Require and instantiate phli:

var phli = require('phli')();

Example Usage

getAddressHistory

Get L & I history for a Philadelpia address:

phli.getAddressHistory('1500 market street', function (err, data) {
  console.log(data);
});

getPermits

Get permits data related to a certain filter criteria, such as zipcode:

phli.getPermits({zip: '19143'}, function (err, data) {
  console.log(data);
});

Available filters example:

{
  zip: '19143', // pass an array of zipcodes to filter on multiple zips
  ward: '44', // 1 - 66; pass an array of wards to filter on multiple wards
  contractor_name: 'John Doe'; pass an array of contractors to filter on multiple contractors
  council_district: '1', // 1 - 10; pass an array of districts to filter on multiple districts
  census_tract: '1', // 1 - 300-and-something; pass an array of tracts to filter on multiple tracts
  start_date: '2011-12-01',
  end_date: '2012-12-01',
  top: '2'
}

getLicenses

Get licenses data related to a certain filter criteria, such as zipcode:

phli.getLicenses({zip: '19143'}, function (err, data) {
  console.log(data);
});

Available filters example:

{
  zip: '19143', // pass an array of zipcodes to filter on multiple zips
  ward: '44', // 1 - 66; pass an array of wards to filter on multiple wards
  council_district: '1', // 1 - 10; pass an array of districts to filter on multiple districts
  census_tract: '1', // 1 - 300-and-something; pass an array of tracts to filter on multiple tracts
  start_date: '2011-12-01',
  end_date: '2012-12-01',
  top: '2'
}

getCases

Get cases data related to a certain filter criteria, such as zipcode:

phli.getLicenses({zip: '19143'}, function (err, data) {
  console.log(data);
});

Available filters example:

{
  zip: '19143', // pass an array of zipcodes to filter on multiple zips
  ward: '44', // 1 - 66; pass an array of wards to filter on multiple wards
  council_district: '1', // 1 - 10; pass an array of districts to filter on multiple districts
  census_tract: '1', // 1 - 300-and-something; pass an array of tracts to filter on multiple tracts
  start_date: '2011-12-01',
  end_date: '2012-12-01'
}

getPermitInfo

Get permit details surrounding a specific permit ID, such as 33333:

phli.getPermitInfo('33333', function (err, data) {
  console.log(data);
});

node-phli's Issues

getType incorrectly injects an " and " into the params.$filter when querying permits

See line 39 of lib/phli.js

Drop underscore dependency

Currently we are only using _.defaults, which we can accomplish by doing something like this:

function applyDefaults(params, defaults) {
  var settings = params || {};

  for(var setting in defaults) {
    if(defaults.hasOwnProperty(setting) && !settings[setting]) {
      settings[setting] = defaults[setting];
    }
  }

  return settings;
}

What do you think?

Return count along with collection

Especially for preview it would be great to have the total count of permits, cases, etc. returned on a query. So the collection array (see #1) shouldn't be the top-level thing. For example:

{
  "count": 457,
  "results": [
     { blah blah },
     ...
  ]
}

Can we get a limited, counted set of cases?

The "cases" type currently hits http://services.phila.gov/PhillyApi/Data/v0.7/Service.svc/violationdetails, which is busted if you try to pass "$top" or "$inlinecount". Is there a way to limit and get counts for the preview?

helpers.buildCommonParams is defined twice

See lines 51 and 100 of helpers.js

When is the presence of $top and $inlinecount permitted in API URLs?

This does not work:
http://services.phila.gov/PhillyApi/Data/v0.7/Service.svc/permits?$format=json&$filter=startswith(locations/zip,%20'19143')&$expand=locations&$top=$inlincount=

And this does work:
http://services.phila.gov/PhillyApi/Data/v0.7/Service.svc/permits?$format=json&$filter=startswith(locations/zip,%20'19143')&$expand=locations

Is this a defect in phli or the API? If the API is behaving as expected, then phli's getType method will need to be modified to account for this, as the library currently makes the first of the above-listed API calls.

Inconsistent API behavior surrounding ?filter= and ?$filter=

I'm seeing inconsistent API response surrounding the $filter param.

For example:

This URL contains a $filter param and does not yield results:
http://services.phila.gov/PhillyApi/Data/v0.7/Service.svc/permits?%24format=json&%24filter=substringof(%27williams%27%2C%20contractor_name)&%24expand=locations&%24top=&%24inlinecount=

This URL is the same as the above but contains a filter param (no '$') and does yield results:
http://services.phila.gov/PhillyApi/Data/v0.7/Service.svc/permits?%24format=json&filter=substringof(%27williams%27%2C%20contractor_name)&%24expand=locations&%24top=&%24inlinecount=

And this URL also queries permits but responds to a $filter param:
http://services.phila.gov/PhillyApi/Data/v0.7/Service.svc/permits?$format=json&$filter=startswith(locations/zip,%20'19143')&$expand=locations&$top=$inlincount=

Is this a defect in phli or in the API? Is there a pattern I'm missing?

OData Library

Doh! OData provides Client Libraries for Javascript and Node.js...that probably would have made things easier. Take a look, maybe it's better to use it?

Query permits and licenses by code / type?

Would be cool to be able to query licenses and permits and pass in a type code or license number. We now have a listing of permit codes and license numbers on PHLAPI.com

http://phlapi.com/permittypes.html
http://phlapi.com/licensetypes.html

Clean up date values

Date values come back looking like this:

/Date(1072328400000)/

Could we convert these to ISO8601 or something like it?

Return collections of things as arrays instead of objects

I changed my mind about this. It's better to get arrays back so we can loop over them for CSV.