Rename geocode

[jgoizueta]

Some minor changes & doc updates for consistency with Isolines

[jgoizueta]

I've renamed the metadata parameter as status.
Now it admits a dictionary to specify which fields to extract to individual columns and a prefix for the column names:

df = gc.geocode(df, street='address', status={'fields':['relevance'], 'prefix'='gc_'})
print(df[df['gc_relevance']>0.7, axis=1)])

df = gc.geocode(df, street='address', status={'fields':['relevance'], 'prefix'=''}).data
print(df[df['relevance']>0.7, axis=1)])

The prefix has a default value of carto_geocode_status_.

I think we could provide some shortcut options e.g. passing just an array (for field names):

df = gc.geocode(df, street='address', status=['relevance']).data
print(df[df['carto_geocode_relevance']>0.7, axis=1)])

Another option would be, instead of using a prefix, assign column names to each field with a dict:

df = gc.geocode(df, street='address', status={'gc_rel': 'relevance'})
print(df[df['gc_rel']>0.7, axis=1)])

cc @alasarr
we should discuss the interface to this new functionality

[alasarr]

I really like your latest suggestion:

df = gc.geocode(df, street='address', status={'gc_rel': 'relevance'})
print(df[df['gc_rel']>0.7, axis=1)])

But having a default config of status to {'gc_status_rel': 'relevance'}. If users don't specify status param, they will get back just the relevance column gc_status_rel

carto_geocode_status_ is a very long prefix, I propose: gc_status_. Long column names are not so comfortable in Python+Pandas

[jgoizueta]

I'll follow @alasarr advice, so this is how this will look:

# Default (equivalent to `status={'gc_status_rel': 'relevance'}`)
# produces columns `gc_status_rel` with geocoding relevance
df = gc.geocode(df, street='address')

# No status columns added
df = gc.geocode(df, street='address', status=None)

# Custom columns
df = gc.geocode(df, street='address', status={'gc_st_rel': 'relevance', 'gc_st_prec': 'precision'})

# Single JSON status column (with relevance, precision, match_types)
df = gc.geocode(df, street='address', status={'gc_status': 'metadata'})

Now, the name of the hash column is carto_geocode_hash. It's tempting to rename it to gc_hash but I'm not sure: this columns shouldn't be used by the users and it's name should avoid collisions with other data columns. While the status columns can be renamed by the user to avoid collision this one cannot be renamed (specially when introducing AFW because sync tables detect geocoded tables by the presence of this column)

[Jesus89]

LGTM! Just solve the conflict with docs/geocode.rst.

Also, I have added a suggestion regarding error messages.