API v2 Wishlist?


#1

What’s on your wishlist for API v2? Right now the plan includes:

  • adding geo methods
  • restoring search (initially title, eventual FTS again)
  • support for object counts
  • querying bills by last action time

at which point we’re probably at feature parity

What else would you like to see?


#2

I’m just starting to work through how I’d use it seriously now. I’ll have some thoughts in a week or two.


#3

Extending filters for various searching combinations.

Person --> Votes --> Bills

for instance

I’m going to fork the repo and try to see what i can contribute.


#4

Restore the following v1 features to jurisdictionNode (the new equivalent of v1’s “metadata”?

  • capitol_timezone
  • abbreviation (as noted elsewhere)
  • latest_update
  • legislature_name
  • legislature_url

Also, some minimal support for biennia (former “terms”) would be good. Even a single bit, indicating whether biennia start on the even or odd year, would be good.

If I had to pick one of these as the most important, it would be latest_update. There are other options for synthesizing the other fields.


#5

I mentioned the removal of terms yesterday, suggesting perhaps adding biennia instead. I incorrectly assumed that “terms” were always two years; that’s not true of LA and MS. I still think biennia may be a good idea, but folks should be aware.

One of the problems with having no terms is that it exacerbates the problem of having sessions without dates. Now these sessions are entirely unanchored in time. IMHO, at least one of these must be fixed; either sessions must have at least a start date (once all are fixed, scraper should break if start date not present), or there must be a term-like entity that somewhat grounds sessions in time.


#7

AFAICT, parties are a bit awkward to handle, because they are members of no Jurisdiction. The only way to retrieve a party is by retrieving it via a legislator who is a member.


#8

terms are definitely gone for good, they were never robust enough to handle the truth (special elections, tiered terms, etc.) but the point about wanting sessions better anchored in time is a fair one. if you’re so inclined it’d be awesome to have some PRs adding missing session dates


#9

I’m curious about the use case for retrieving a party? in the past there was no way to do this (since parties weren’t entities, just labels) and while it is technically possible now I’m trying to think of when you’d want to do so


#10

[Re adding session dates:] Would you prefer them bunched into a few PR’s, or one PR per state?


#11

[Re parties] The use case is for enumeration of the parties, e.g. to create a picklist, and that can be done by traversing all the legislators in a state, so it’s a weak need.


#12

The use of “Home Office” and “District Office” in the “note” field of legislator offices is inconsistent, perhaps because the terms are strange to some, myself included. I expect there to be a value for “an office at the capitol” and “an office in the legislator’s home district”. In New Hampshire, the terms are used conflictingly for the House and Senate; in the Senate, the “Home Office” is the one at the capitol, whereas in the House the “Home Office” is in the home district.

Also, the legislator sortName, familyName, and givenName are all empty.


#13

Batched should be fine, whatever is manageable for you. I imagine one review that they’re all sane would be enough on our part to merge them.

And re: parties, that is an interesting point. We may have to provide somewhat static metadata on that eventually- there wasn’t a great way to get it in the past either (the parties array wasn’t used for per-state validation, but was just a hint that was typically copied & pasted to just be R/D/I even in states w/ more complex party breakdowns)


#14

This might be an upstream issue or a scraper issue, but if you want to file one that’d be best for this.

As for names, none are guaranteed to be provided, we don’t get broken apart names upstream for most states. sortName is only provided in cases where it should differ from name.


#15

Yeah, I looked at the scrapers, the “Home Office” thing seems to be a NH issue.

For sortName, I expected to see “Ward, Ruth” for name=“Ruth Ward”, but it’s blank. Would you expect a sortName in this case?


#16

You might consider providing some kind of internal “activitySince” date parameter on the bills() query to restrict the actions and votes to only ones since a prior query. They can grow very large, especially with roll calls.

An alternative implementation would be to put a “since” parameter on the votes() and actions() within BillNode. Note that actions doesn’t take parameters now.


#17

It would be nice to have the ability to fetch all memberships for a person, even inactive/old ones.


#18

So there’s good news & bad news on that one. The API does support/return past memberships if they exist in the database, but in the interest of starting w/ clean data we didn’t bring over old legislators/memberships which is probably why it looks like it doesn’t. Going forward we’d keep these around, but I’m not sure if there’s an appetite right now to spend the time filling old roles in.

Do you have a specific use case in mind for this data? I’m curious how well it’d be met if we did manage to port old v1 roles to the new DB.


#19

The API does support/return past memberships if they exist in the database, but in the interest of starting w/ clean data we didn’t bring over old legislators/memberships which is probably why it looks like it doesn’t.

Well, (a) this is the good news I was hoping for, and (b) how would I get all memberships for a person? The documentation for the PersonNode suggests I can obtain the currentMemberships, is there a corresponding allMemberships undocumented field? Or is currentMemberships really all memberships?

(I realize this is kind of silly, since only data from 2017 onwards would be stored, but moving forward it may be useful to get the prior memberships of a legislator who has left public life.)


#20

…moving forward it may be useful to get the prior memberships of a legislator who has left public life.

Even more significant is the case of legislators who have moved committees or even chamber, but are still active, and thus their record is more likely to be scrutinized.


#21

I’ve opened an issue to make sure we properly expose these, I didn’t realize I’d closed off the memberships endpoint. I’ll likely add a previousMemberships as an analog to currentMemberships since I think being able to get them separately will probably provide a cleaner interface (and is similar to how we handled this in the v1 API)