streettraffic.map_resource

streettraffic.map_resource.utility

class streettraffic.map_resource.utility.Utility(settings: typing.Dict) → None[source]

Bases: object

This class has some utility function for map resources

In order to generate Url Resources, you should get app_id and app_code at developer.HERE.com Specific instructions can be found here: https://developer.here.com/rest-apis/documentation/traffic/common/credentials.html

app_id

str – The app id acquired from https://developer.here.com/

app_code

str – The app code acquired from https://developer.here.com/

map_tile_base_url

str – the base url of the map image tile requests an exmaple can be found here: https://developer.here.com/api-explorer/rest/traffic/traffic-tile

json_tile_base_url

str – the base url of the traffic json tile requests an example can be found here: https://developer.here.com/api-explorer/rest/traffic/traffic-flow-quadkey

Parameters:settings (Dict) – The settings of your app

Example

>>> settings = {
        'app_id': 'F8aPRXcW3MmyUvQ8Z3J9',
        'app_code' : 'IVp1_zoGHdLdz0GvD_Eqsw',
        'map_tile_base_url': 'https://1.traffic.maps.cit.api.here.com/maptile/2.1/traffictile/newest/normal.day/',
        'json_tile_base_url': 'https://traffic.cit.api.here.com/traffic/6.2/flow.json?'
    }
>>> util = Utility(settings)
>>> util.app_id
'F8aPRXcW3MmyUvQ8Z3J9'
assemble_matrix_images(matrix: pandas.core.frame.DataFrame) → pandas.core.frame.DataFrame[source]

This function load a map_tile url matrix and assemble it as a image matrix. Also it will print out a image for you to see.

Parameters:matrix (pd.DataFrame) – a map_tile url matrix
Returns:matrix of images
Return type:DataFrame
get_area_polygon_collection() → typing.List[source]

This function load the route_collection.json in the your current directory and return the its python equivalent list

Returns:a list of object like {'area_description': ..., 'polygon': ...}
Return type:List
static get_area_tile_matrix(list_points: typing.List, zoom: int, use_polygon: bool = False) → pandas.core.frame.DataFrame[source]

This function takes the coordinates from list_points and calculate their tile (col, row), then it generate a matrix of tiles to cover the square area spanned by those coordinates. If use_polygon == True, however, then we generate a polygon given by self.produce_polygon, and further eliminate any tiles in the matrix that are not inside of the polygon

###^^^^^^*####  (in this example, two coordinates are denoted as *
#  ^^^^^^^   #   and this function should generate tile to cover the
#  ^^^^^^^   #   area denoted by ^ and *)
###*^^^^^^####
Parameters:
  • list_points (List) – list of GPS coordinates that you want to add
  • zoom (int) – the zoom level
  • use_polygon (bool) – If plot_polygon == True, then we generate a polygon given by self.produce_polygon, and further eliminate any tiles in the matrix that are not inside of the polygon
Returns:

a matrix filled with tiles number (col, row)

Return type:

DataFrame

Example

>>> # or checkout the unittest for this function
>>> example_list_points = [(33.766764, -84.409533), (33.740003, -84.368978)]
get_area_tile_matrix_url(resource_type: str, list_points: typing.List, zoom: int, use_polygon=False) → pandas.core.frame.DataFrame[source]

This function takes the coordinates from list_points and calculate their tile (col, row), then it generate a matrix of tiles URLs (either map_tile urls or traffic_json urls) to cover the square area spanned by those coordinates.

If use_polygon == True, however, then we generate a polygon given by self.produce_polygon, and further eliminate any tiles URLs in the matrix that are not inside of the polygon

###^^^^^^*####  (in this example, two coordinates are denoted as *
#  ^^^^^^^   #   and this function should generate tile to cover the
#  ^^^^^^^   #   area denoted by ^ and *)
###*^^^^^^####
Parameters:
  • resource_type (str) – what types of URLs do you want, it can either be map_tile or traffic_json
  • list_points (List) – list of GPS coordinates that you want to add
  • zoom (int) – the zoom level
  • use_polygon (bool) – If plot_polygon == True, then we generate a polygon given by self.produce_polygon, and further eliminate any tiles in the matrix that are not inside of the polygon
Returns:

a matrix filled with tiles number (col, row)

Return type:

DataFrame

Example

>>> # or checkout the unittest for this function
>>> example_list_points = [(33.766764, -84.409533), (33.740003, -84.368978)]
static get_distance(point1: tuple, point2: tuple, location_type: str = 'latlon', distance_formula: str = 'great_circle', unit: str = 'meters') → float[source]

This function returns the distance between point1 and poin2 in meters.

Note

this function is a quick wraper for geopy.

Parameters:
  • point1 (tuple) – a GPS coordinates
  • point2 (tuple) – a GPS coordinates
  • location_type (str) – “latlon” meaning the format is (latitude, longitude) for point1 and point2
  • distance_formula (str) – two options for distance formula, either 'great_circle' or 'vincenty'
  • unit (str) – “meters”
Returns:

distance between point1 and point2

Return type:

float

get_map_tile_resource(location_data: tuple, location_type: str, zoom: int, img_size: int) → str[source]

This function generates a url to get map_tile.

For map_tile resource details, refer to https://developer.here.com/rest-apis/documentation/enterprise-map-tile/topics/quick-start.html

Parameters:
  • location_data (tuple) – either (latitude, longitude) or (column, row)
  • location_type (str) – either “latlon” or “colrow”
  • zoom (int) – the zoom level
  • img_size (int) – the image size. There are two options: 256 or 512
Returns:

the url for requesting a map tile resource

Return type:

str

Example

>>> # or checkout the unittest for this function
>>> settings = {
        'app_id': 'F8aPRXcW3MmyUvQ8Z3J9',
        'app_code' : 'IVp1_zoGHdLdz0GvD_Eqsw',
        'map_tile_base_url': 'https://1.traffic.maps.cit.api.here.com/maptile/2.1/traffictile/newest/normal.day/',
        'json_tile_base_url': 'https://traffic.cit.api.here.com/traffic/6.2/flow.json?'
    }
>>> util = Utility(settings)
>>> util.get_map_tile_resource((33.670156, -84.325984),"latlon", 14, 512)
'https://1.traffic.maps.cit.api.here.com/maptile/2.1/traffictile/newest/normal.day/14/4354/6562/512/png8?app_id=F8aPRXcW3MmyUvQ8Z3J9&app_code=IVp1_zoGHdLdz0GvD_Eqsw'
static get_quadkeys(col: int, row: int, zoom: int) → str[source]

This function is used to encode (col, row, zoom) as quadkey. For details, refer to https://developer.here.com/rest-apis/documentation/traffic/common/map_tile/topics/quadkeys.html

Parameters:
  • col (int) – column
  • row (int) – row
  • zoom (int) – the zoom level
Returns:

quadkey

Return type:

str

Example

>>> # or checkout the unittest for this function
>>> settings = {
        'app_id': 'F8aPRXcW3MmyUvQ8Z3J9',
        'app_code' : 'IVp1_zoGHdLdz0GvD_Eqsw',
        'map_tile_base_url': 'https://1.traffic.maps.cit.api.here.com/maptile/2.1/traffictile/newest/normal.day/',
        'json_tile_base_url': 'https://traffic.cit.api.here.com/traffic/6.2/flow.json?'
    }
>>> util = Utility(settings)
>>> util.get_quadkeys(35210, 21493, 16)
"1202102332221212"
get_route_tile_matrix_url() → pandas.core.frame.DataFrame[source]

This function load the route_collection.json in the your current directory and return a traffic_json url matrix

Returns:a traffic_json url matrix that we can use to crawl data
Return type:DataFrame
static get_tile(lat: float, lon: float, zoom: int) → typing.List[source]

Given a GPS coordiante and zoom level, generate column and row information for HERE API usage. For details, please visit https://developer.here.com/rest-apis/documentation/enterprise-map-tile/topics/key-concepts.html for reference.

Parameters:
  • lat (float) – latitue
  • lon (float) – longitude
  • zoom (int) – the zoom level
Returns:

[col, row]

Return type:

List

Example

>>> # or checkout the unittest for this function
>>> settings = {
        'app_id': 'F8aPRXcW3MmyUvQ8Z3J9',
        'app_code' : 'IVp1_zoGHdLdz0GvD_Eqsw',
        'map_tile_base_url': 'https://1.traffic.maps.cit.api.here.com/maptile/2.1/traffictile/newest/normal.day/',
        'json_tile_base_url': 'https://traffic.cit.api.here.com/traffic/6.2/flow.json?'
    }
>>> util = Utility(settings)
>>> util.get_tile(52.525439, 13.38727, 12)
[2200, 1343]
get_traffic_json_resource(location_data: tuple, location_type: str, zoom: int) → str[source]

This function generates a url to get traffic_json resource.

For traffic_json resource details, refer to https://developer.here.com/rest-apis/documentation/traffic/topics/quick-start.html

Parameters:
  • location_data (tuple) – either (latitude, longitude) or (column, row)
  • location_type (str) – either “latlon” or “colrow”
  • zoom (int) – the zoom level
Returns:

the url for requesting a traffic json resource

Return type:

str

Example

>>> # or checkout the unittest for this function
>>> settings = {
        'app_id': 'F8aPRXcW3MmyUvQ8Z3J9',
        'app_code' : 'IVp1_zoGHdLdz0GvD_Eqsw',
        'map_tile_base_url': 'https://1.traffic.maps.cit.api.here.com/maptile/2.1/traffictile/newest/normal.day/',
        'json_tile_base_url': 'https://traffic.cit.api.here.com/traffic/6.2/flow.json?'
    }
>>> util = Utility(settings)
>>> util.get_traffic_json_resource((34.9237, -82.4383), "latlon", 14)
'https://traffic.cit.api.here.com/traffic/6.2/flow.json?app_id=F8aPRXcW3MmyUvQ8Z3J9&app_code=IVp1_zoGHdLdz0GvD_Eqsw&quadkey=03200303033202&responseattributes=sh,fc'
static matrix_coverage(matrix: pandas.core.frame.DataFrame)[source]

Generate some statistical information about how many valid query tiles are there in your provided matrix

Parameters:matrix (pd.DataFrame) – The JSON raw data
Returns:None, but it prints out some information about your matrix
static produce_polygon(polygon_ordered_coordinates: typing.List, zoom: int, plot_polygon: bool = False) → matplotlib.path.Path[source]

This function use matplotlib.path to create a Path/polygon object. Later we can use this Path/polygon object to invoke Path.contains_point() method. For more details on contains_point(), refer to https://stackoverflow.com/questions/21328854/shapely-and-matplotlib-point-in-polygon-not-accurate-with-geolocation

Parameters:
  • polygon_ordered_coordinates (List) – an ordered list of points that composes a polygon
  • zoom (int) – the zoom level
  • plot_polygon (bool) – If plot_polygon == True, we use matplotlib to plot the polygon
Returns:

a Path polygon

Return type:

matplotlib.path.Path

Example

>>> # or checkout the unittest for this function
>>> example_polygon_ordered_coordinates = [[25.890099, -80.264561], [25.851873, -80.308744], [25.81123, -80.248538], [25.848596, -80.215765]]
static read_geojson_polygon(geojson_polygon: str) → typing.List[source]

Given a polygon in geojson string format, this function outputs a polygon list that consist of coordiantes that has [latitude, longitude] format.

Parameters:geojson_polygon (str) – a polygon of geojson encoding.
Returns:a list that consist of coordiantesthat has [latitude, longitude] format
Return type:List

Example

>>> checkout the unittest for this function
>>> geojson_polygon = '''
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -84.38658714294434,
              33.76908761144743
            ],
            [
              -84.37294006347656,
              33.766590334877485
            ]
          ]
        ]
      },
      "properties": {}
    }
  ]
‘’’ # notice this should be a string
>>> settings = {
        'app_id': 'F8aPRXcW3MmyUvQ8Z3J9',
        'app_code' : 'IVp1_zoGHdLdz0GvD_Eqsw',
        'map_tile_base_url': 'https://1.traffic.maps.cit.api.here.com/maptile/2.1/traffictile/newest/normal.day/',
        'json_tile_base_url': 'https://traffic.cit.api.here.com/traffic/6.2/flow.json?'
    }
>>> util = Utility(settings)
>>> util.read_geojson_polygon(geojson_polygon)
[[33.76908761144743, -84.38658714294434],
[33.766590334877485, -84.37294006347656]]
register_area_polygon(area_description: str, geojson_polygon: str) → None[source]

This function register an area polygon and store it in area_collection.json

Parameters:
  • area_description (str) – a description of the area
  • geojson_polygon (str) – the geojson formatted string polygon
Returns:

None

register_route_tile(routing_info: typing.Dict, zoom: int = 14) → None[source]

This function takes routing_info generated by Google Direction API and store a route_collection.json in the your current directory (the directory that you used to run a file and call this function)

Parameters:
  • routing_info (Dict) – The response document generated by Google Direction API
  • zoom (int) – the zoom level. Default is set to 14 because it is the best level for meaningful details and it is also comparitively economical.
Returns:

None