pyportall.api.engine

`core`

Module where core API-related classes live.

`APIClient`

This class holds the direct interface to Portall's API. Other classes may need to use one API client to actually send requests to the API.

`init(self, api_key=None, batch=False, preflight=False)` `special`

When instantiating an API client, you will provide an API key and optionally opt for batch or preflight modes.

In preflight mode, requests to the API will not be executed. Instead, the API returns the estimated cost in credits for such request.

Use batch mode when requests take longer to execute than the default API timeout (around 15s).

Parameters:

Name	Type	Description	Default
`api_key`	`Optional[str]`	API key to use with Portall's API, in case no API key is available via the `PYPORTALL_API_KEY` environment variable. Please contact us if you need one.	`None`
`batch`	`Optional[bool]`	Whether the client will work in batch mode or not.	`False`
`preflight`	`Optional[bool]`	Whether the client will work in preflight mode or not.	`False`

Exceptions:

Type	Description
`PyPortallException`	Raised if no API key is available either through the `api_key` parameter or the `PYPORTALL_API_KEY` environment variable.

`call_indicators(self, url, input)`

Send requests to Portall's indicator API.

Takes an arbitrary object and, as long as it can be transformed into a JSON string, sends it to the indicator API. It deals with preflight and batch mode according to the settings defined upon creation of the client.

Parameters:

Name	Type	Description	Default
`url`	`str`	URL of the specific API endpoint in question.	required
`input`	`Any`	Any python object that can be encoded to a JSON string.	required

Returns:

Type	Description
`Any`	The Python object derived from the JSON received by the API.

Exceptions:

Type	Description
`AuthError`	Authentication has failed, probably because of a wrong API key.
`BatchError`	A batch request has failed, because of an error or because the batch timeout has expired.
`PreFlightException`	Raised in preflight mode, includes the number of estimated credits that the actual request would consume.
`PyPortallException`	Generic API exception.
`RateLimitError`	The request cannot be fulfilled because either the company credit has run out or the maximum number of allowed requests per second has been exceeded.
`TimeoutError`	A regular (non-batch) request has timed out.
`ValidationError`	The format of the request is not valid.

`call_metadata(self)`

Send requests to Portall's metadata API.

Returns:

Type	Description
`Any`	The Python object derived from the JSON received by the API.

Exceptions:

Type	Description
`PyPortallException`	Generic API exception.

`delete(self, endpoint, params=None, headers=None)`

Send DELETE requests to Portall's API.

Parameters:

Name	Type	Description	Default
`endpoint`	`str`	URL to send the request to.	required
`params`	`Optional[Dict]`	Parameters to be sent as part of the final URL.	`None`
`headers`	`Optional[Dict]`	Headers to be added to the request, if any.	`None`

Exceptions:

Type	Description
`AuthError`	Authentication has failed, probably because of a wrong API key.
`PyPortallException`	Generic API exception.
`RateLimitError`	The request cannot be fulfilled because either the company credit has run out or the maximum number of allowed requests per second has been exceeded.
`TimeoutError`	Request has timed out.

`get(self, endpoint, params=None, headers=None)`

Send GET requests to Portall's API.

Parameters:

Name	Type	Description	Default
`endpoint`	`str`	URL to send the request to.	required
`params`	`Optional[Dict]`	Parameters to be sent as part of the final URL.	`None`
`headers`	`Optional[Dict]`	Headers to be added to the request, if any.	`None`

Returns:

Type	Description
`Any`	The Python object derived from the JSON received by the API.

Exceptions:

Type	Description
`AuthError`	Authentication has failed, probably because of a wrong API key.
`PyPortallException`	Generic API exception.
`RateLimitError`	The request cannot be fulfilled because either the company credit has run out or the maximum number of allowed requests per second has been exceeded.
`TimeoutError`	Request has timed out.

`post(self, endpoint, body, params=None, headers=None)`

Send POST requests to Portall's API.

Parameters:

Name	Type	Description	Default
`endpoint`	`str`	URL to send the request to.	required
`body`	`str`	JSON string.	required
`params`	`Optional[Dict]`	Parameters to be sent as part of the final URL.	`None`
`headers`	`Optional[Dict]`	Headers to be added to the request, apart from content-type.	`None`

Returns:

Type	Description
`Any`	The Python object derived from the JSON received by the API.

Exceptions:

Type	Description
`AuthError`	Authentication has failed, probably because of a wrong API key.
`PyPortallException`	Generic API exception.
`RateLimitError`	The request cannot be fulfilled because either the company credit has run out or the maximum number of allowed requests per second has been exceeded.
`TimeoutError`	Request has timed out.
`ValidationError`	The format of the request is not valid.

`put(self, endpoint, body, params=None, headers=None)`

Send PUT requests to Portall's API.

Parameters:

Name	Type	Description	Default
`endpoint`	`str`	URL to send the request to.	required
`body`	`str`	JSON string.	required
`params`	`Optional[Dict]`	Parameters to be sent as part of the final URL.	`None`
`headers`	`Optional[Dict]`	Headers to be added to the request, apart from content-type.	`None`

Returns:

Type	Description
`Any`	The Python object derived from the JSON received by the API.

Exceptions:

Type	Description
`AuthError`	Authentication has failed, probably because of a wrong API key.
`PyPortallException`	Generic API exception.
`RateLimitError`	The request cannot be fulfilled because either the company credit has run out or the maximum number of allowed requests per second has been exceeded.
`TimeoutError`	Request has timed out.
`ValidationError`	The format of the request is not valid.

`APIHelper`

Ensure a common structure for helpers that actually do things.

`init(self, client)` `special`

Class constructor to attach the coresponding API client.

Parameters:

Name	Type	Description	Default
`client`	`APIClient`	API client object that the helper will use to actually send requests to the API when it has to.	required

`geopandas`

Module where the (Geo)Pandas helpers live.

`GeocodingHelper`

Help with street addresses.

`resolve(self, df, options=None)`

Find latitude and longitude for a number of street addresses.

Turn a DataFrame with street addresses into a GeoDataFrame where the geometry column derives from the corresponding latitude and longitude, once those addresses have been properly geocoded.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	DataFrame with at least one `street` column that includes full or partial addresses to be geocoded. Even though `street` is the only mandatory column and can contain arbitrary, partial or full addreses, geocoding typically works better if the full address is split into several fields. Therefore, other columns can help improve the accuracy of the geocoding process, namely `country`, `county`, `city`, `district` and `postal_code`.	required
`options`	`Optional[pyportall.api.models.lbs.GeocodingOptions]`	Default values for the `country`, `county`, `city`, `district` and `postal_code` columns of the DataFrame, when they are not present.	`None`

Returns:

Type	Description
`GeoDataFrame`	A GeoDataFrame with all the geocoding columns plus the geometry column with the actual points derived from the geocoding process.

`IndicatorHelper`

Help with indicators.

`resolve_aggregated(self, gdf, indicator=None, moment=None)`

Find the value of an aggregated indicator for a number of target geometries in a particular moment in time.

Given a moment in time, a number of geometries and a target indicator, find the aggregated indicator value for each of the geometries in the specified moment.

Parameters:

Name	Type	Description	Default
`gdf`	`GeoDataFrame`	GeoDataFrame with a `geometry` column that stands for the geometries to be used on the calculations.	required
`indicator`	`Optional[pyportall.api.models.indicators.Indicator]`	The indicator to be computed.	`None`
`moment`	`Optional[pyportall.api.models.indicators.Moment]`	The moment in time that will be used for the calculations.	`None`

Returns:

Type	Description
`GeoDataFrame`	A copy of the original GeoDataFrame with a new column `value` with the computed values for each geometry.

`resolve_disaggregated(self, polygon, indicator, moment)`

Find the disaggregated values for an indicator over a target geometry in a particular moment in time.

Given a moment in time, one geometry and a target indicator, find the H3 cells underneath the given geometry and compute the indicator value for each of them.

Parameters:

Name	Type	Description	Default
`polygon`	`Polygon`	Geometry to be used on the calculations.	required
`indicator`	`Indicator`	The indicator to be computed.	required
`moment`	`Moment`	The moment in time that will be used for the calculations.	required

Returns:

Type	Description
`GeoDataFrame`	A GeoDataFrame with one row per H3 cells and columns: `id` with the H3 cell id, `geometry` with the geometry of the H3 cells, `value` with the indicator value for the cell, and `weight`, which is useful if you want to aggregate the data from this disaggregated geodataframe yourself.

`IsolineHelper`

Help with isovists.

`resolve(self, gdf, options=None)`

Find isolines (space that can be reached in a certain amount of time from a given point in space).

Turn a GeoDataFrame with points and other parameters the define isolines into another GeoDataFrame where the geometry column is formed by the polygons that translate to such isoline definitions.

Parameters:

Name	Type	Description	Default
`gdf`	`GeoDataFrame`	GeoDataFrame with a `geometry` column with the target points and other columns to help define the isolines, Such columns are `mode`, `range`, and `moment`.	required
`options`	`Optional[pyportall.api.models.lbs.IsolineOptions]`	Default values for the `mode`, `range`, and `moment` columns of the original GeoDataFrame, when they are not present.	`None`

Returns:

Type	Description
`GeoDataFrame`	A GeoDataFrame with all the isoline definition columns plus a `destination` column with the original points. The geometry column now holds the actual polygons derived from computing the isolines.

`IsovistHelper`

Help with isolines.

`resolve(self, gdf, options=None)`

Find isovists (space visible from a given point in space).

Turn a GeoDataFrame with points and other parameters the define isovists into another GeoDataFrame where the geometry column is formed by the polygons that translate to such isovist definitions.

Parameters:

Name	Type	Description	Default
`gdf`	`GeoDataFrame`	GeoDataFrame with a `geometry` column with the target points and other columns to help define the isovists, Such columns are `radius_m`, `num_rays`, `heading_deg` and `fov_deg`.	required
`options`	`Optional[pyportall.api.models.lbs.IsovistOptions]`	Default values for the `radius_m`, `num_rays`, `heading_deg` and `fov_deg` columns of the original GeoDataFrame, when they are not present.	`None`

Returns:

Type	Description
`GeoDataFrame`	A GeoDataFrame with all the isovist definition columns plus a `destination` column with the original points. The geometry column now holds the actual polygons derived from computing the isovists.

`PortallDataFrameHelper`

Help with Portall's GeoDataFrame wrappers.

`all(self)`

Get all the dataframes available in Portall's database.

Returns:

Type	Description
`List[pyportall.api.models.geopandas.PortallDataFrame]`	A list of GeoDataFrame-compatible dataframes.

`get(self, id)`

Get just one of the dataframes available in Portall's database.

Parameters:

Name	Type	Description	Default
`id`	`UUID4`	Id. of the dataframe to be retrieved.	required

Returns:

Type	Description
`Optional[pyportall.api.models.geopandas.PortallDataFrame]`	GeoDataFrame-compatible dataframe.

`metadata`

Module where the metadata helpers live.

`MetadataHelper`

Help with indicator metadata.

`init(self, client)` `special`

Class constructor to attach the corresponding API client.

Parameters:

Name	Type	Description	Default
`client`	`APIClient`	API client object that the helper will use to actually send requests to the metadata API when it has to.	required

`all(self)`

Get all the indicators available in the metadata database.

Returns:

Type	Description
`List[pyportall.api.models.metadata.IndicatorMetadata]`	A list of indicators with their metadata.

`get(self, indicator_code)`

Get just one of the indicators available in the metadata database.

Parameters:

Name	Type	Description	Default
`indicator_code`	`str`	Code of the indicator to be retrieved.	required

Returns:

Type	Description
`Optional[pyportall.api.models.metadata.IndicatorMetadata]`	Indicator with its metadata.

`refresh(self)`

Update the metadata with a fresh copy from the database.

pyportall.api.engine

core

APIClient

__init__(self, api_key=None, batch=False, preflight=False) special

call_indicators(self, url, input)

call_metadata(self)

delete(self, endpoint, params=None, headers=None)

get(self, endpoint, params=None, headers=None)

post(self, endpoint, body, params=None, headers=None)

put(self, endpoint, body, params=None, headers=None)

APIHelper

__init__(self, client) special

geopandas

GeocodingHelper

resolve(self, df, options=None)

IndicatorHelper

resolve_aggregated(self, gdf, indicator=None, moment=None)

resolve_disaggregated(self, polygon, indicator, moment)

IsolineHelper

resolve(self, gdf, options=None)

IsovistHelper

resolve(self, gdf, options=None)

PortallDataFrameHelper

all(self)

get(self, id)

metadata

MetadataHelper

__init__(self, client) special

all(self)

get(self, indicator_code)

refresh(self)

`core`

`APIClient`

`init(self, api_key=None, batch=False, preflight=False)` `special`

`call_indicators(self, url, input)`

`call_metadata(self)`

`delete(self, endpoint, params=None, headers=None)`

`get(self, endpoint, params=None, headers=None)`

`post(self, endpoint, body, params=None, headers=None)`

`put(self, endpoint, body, params=None, headers=None)`

`APIHelper`

`init(self, client)` `special`

`geopandas`

`GeocodingHelper`

`resolve(self, df, options=None)`

`IndicatorHelper`

`resolve_aggregated(self, gdf, indicator=None, moment=None)`

`resolve_disaggregated(self, polygon, indicator, moment)`

`IsolineHelper`

`resolve(self, gdf, options=None)`

`IsovistHelper`

`resolve(self, gdf, options=None)`

`PortallDataFrameHelper`

`all(self)`

`get(self, id)`

`metadata`

`MetadataHelper`

`init(self, client)` `special`

`all(self)`

`get(self, indicator_code)`

`refresh(self)`