API Services Schemas

Locations API

class bingmaps.urls.locations_build_urls.Location(extra=None, only=(), exclude=(), prefix='', strict=False, many=False, context=None, load_only=(), dump_only=(), partial=False)[source]

Main class for Locations API schema

Data Fields:

Variables:
  • version –

    A string containing v and an integer that specifies the version of the Bing Maps REST Services.

    • default: v1
  • restApi –

    A part of the URL path that identifies the REST API.

    • default: ‘Locations’ (for Locations API services)
  • resourcePath – A part of the URL path that specifies a resource, such as an address or landmark.

This schema helps in creating the main parameters of all types of locations API based services (location by address, location by point, location by query. The above mentioned data fields make up the main parameters of the url.

Example:

The below example can show you a typical example for how the main URL parameters can be passed in as a dictionary

>>> data = {'version': 'v1',
...         'restApi': 'Locations',
...         'resourcePath': ''}

When you dump an empty dictionary, the class helps you in filling the dictionary with default values. You can see the same behaviour in the below example:

>>> data = {}
>>> schema = Location()
>>> schema.dump(data).data
OrderedDict([('version', 'v1'), ('restApi', 'Locations')])

Note

Location class is common for all the location based services with the same default data.

Location By Address

class bingmaps.urls.locations_build_urls.LocationByAddressSchema(extra=None, only=(), exclude=(), prefix='', strict=False, many=False, context=None, load_only=(), dump_only=(), partial=False)[source]

Inherits from Location

Schema for query parameters in which all the fields will be in a ordered way. All the fields will be dumped in the same order as mentioned in the schema.

Data Fields for the schema (taken from https://msdn.microsoft.com/en-us/library/ff701714.aspx):

Variables:
  • adminDistrict[Optional] – A string that contains a subdivision, such as the abbreviation of a US state
  • locality[Optional] – A string that contains the locality, such as a US city
  • postalCode[Optional] – An integer value that contains the postal code, such as a US ZIP Code
  • addressLine[Optional] – A string specifying the street line of an address
  • countryRegion[Optional] – A string specifying the ISO country code
  • c[Optional] – A string specifying the culture parameter
  • o[Optional] –

    A string for specifying the format of output(response) Ex. - xml/json

    • If empty, default output would be a JSON data string
    • If given xml, the output would be an xml data string
  • includeNeighborhood[Optional] –

    One of the following values

    • 1: Include neighborhood information when available
    • 0 [default]: Do not include neighborhood information
  • include[Optional] –

    The only value for this parameter is ciso2. When you specify include=ciso2, the two-letter ISO country code is included for addresses in the response

    • default=’ciso2’
  • maxResults[Optional] –

    An integer between 1 and 20 (number of results)

    • default=20
  • key[Required] – Bing maps api key - Required

This schema helps in serializing the data.

Post-Dump:
After dumping the data, build_query_string builds up the queryParameters string. The final value after dumping the data would be a string.

Example:

>>> data = { 'adminDistrict': 'WA',
...          'locality': 'Seattle',
...          'c': 'te',
...          'o': 'xml',
...          'includeNeighborhood': 1,
...          'key': 'abs'
...         }
>>> query = LocationByAddressSchema()
>>> query.dump(data).data
OrderedDict([('version', 'v1'), ('restApi', 'Locations'), ('query', 'adminDistrict=WA&locality=Seattle&c=te&o=xml&includeNeighborhood=1&include=ciso2&maxResults=20&key=abs')])

In the output, you can see ‘include’, ‘maxResults’ in the string although we haven’t specified any values because they are default values specified in the schema.

build_query_string(data)[source]

This method occurs after dumping the data into the class.

Args:
data (dict): dictionary of all the query values
Returns:
data (dict): ordered dict of all the values

Location By Point

class bingmaps.urls.locations_build_urls.LocationByPointSchema(extra=None, only=(), exclude=(), prefix='', strict=False, many=False, context=None, load_only=(), dump_only=(), partial=False)[source]

Inherits from Location

Schema for query parameters in which all the fields will be in a ordered way. All the fields will be dumped in the same order as mentioned in the schema.

Data Fields for the schema (taken from https://msdn.microsoft.com/en-us/library/ff701710.aspx):

Variables:
  • point[Required] – A point on the Earth specified by a latitude and longitude.
  • includeEntityTypes[Optional] –

    A comma separated list of entity types selected from the following options:

    • Address
    • Neighborhood
    • PopulatedPlace
    • Postcode1
    • AdminDivision1
    • AdminDivision2
    • CountryRegion

    These entity types are ordered from the most specific entity to the least specific entity. When entities of more than one entity type are found, only the most specific entity is returned. For example, if you specify Address and AdminDistrict1 as entity types and entities were found for both types, only the Address entity information is returned in the response. One exception to this rule is when both PopulatedPlace and Neighborhood entity types are specified and information is found for both. In this case, the information for both entity types is returned. Also, more than one Neighborhood may be returned because the area covered by two different neighborhoods can overlap.

  • includeNeighborhood[Optional] –

    One of the following values:

    • 1: Include neighborhood information when available.
    • 0 [default]: Do not include neighborhood information.
  • include[Optional] – The only value for this parameter is ciso2. When you specify include=ciso2, the two-letter ISO country code is included for addresses in the response.
  • c[Optional] – A string specifying the culture parameter
  • o[Optional] –

    A string for specifying the format of output(response) Ex. - xml/json

    • If empty, default output would be a JSON data string
    • If given xml, the output would be an xml data string
  • maxResults[Optional] –

    An integer between 1 and 20 (number of results)

    • default=20
  • key[Required] –

    Bing maps api key

    • Required
Post-Dump:
After dumping the data, build_query_string builds up the queryParameters string. The final value after dumping the data would be a string. The string would be similar to the one mentioned in the below example.

Example:

>>> data = { 'point': '47.64054,-122.12934',
...          'includeEntityTypes': 'Address',
...          'c': 'te',
...          'o': 'xml',
...          'includeNeighborhood': 1,
...          'key': 'abs'
...         }
>>> query = LocationByPointSchema()
>>> query.dump(data).data
OrderedDict([('version', 'v1'), ('restApi', 'Locations'), ('query', '47.64054,-122.12934?includeEntityTypes=Address&includeNeighborhood=1&include=ciso2&c=te&o=xml&maxResults=20&key=abs')])

In the output, you can see ‘include’, ‘maxResults’ in the string although we haven’t specified any values because they are default values specified in the schema.

build_query_string(data)[source]

This method occurs after dumping the data into the class.

Args:
data (dict): dictionary of all the query values
Returns:
data (dict): ordered dict of all the values

Location By Query

class bingmaps.urls.locations_build_urls.LocationByQuerySchema(extra=None, only=(), exclude=(), prefix='', strict=False, many=False, context=None, load_only=(), dump_only=(), partial=False)[source]

Inherits from Location

Schema for query parameters in which all the fields will be in a ordered way. All the fields will be dumped in the same order as mentioned in the schema.

Data Fields for the schema (taken from https://msdn.microsoft.com/en-us/library/ff701711.aspx):

Variables:
  • q[Required] – A string (query) that contains information about a location, such as an address or landmark name.
  • includeNeighborhood[Optional] –

    One of the following values:

    • 1: Include neighborhood information when available.
    • 0 [default]: Do not include neighborhood information.
  • include[Optional] –

    One or more of the following options:

    • queryParse: Specifies that the response shows how the query string was parsed into address values, such as addressLine, locality, adminDistrict, and postalCode.
    • ciso2: Specifies to include the two-letter ISO country code.

    If you specify more than one include value, separate the values with a comma.

  • c[Optional] – A string specifying the culture parameter
  • o[Optional] –

    A string for specifying the format of output(response) Ex. - xml/json

    • If empty, default output would be a JSON data string
    • If given xml, the output would be an xml data string
  • maxResults[Optional] –

    An integer between 1 and 20 (number of results)

    • default=20
  • key[Required] –

    Bing maps api key

    • Required
Post-Dump:
After dumping the data, build_query_string builds up the queryParameters string. The final value after dumping the data would be a string. The string would be similar to the one mentioned in the below example.

Example:

>>> data = {'q': '1014 Oatney Ridge Ln., Morrisville,NC-27560',
...         'key': 'abs'}
>>> query = LocationByQuerySchema()
>>> query.dump(data).data
OrderedDict([('version', 'v1'), ('restApi', 'Locations'), ('query', 'q=1014%20Oatney%20Ridge%20Ln.%2C%20Morrisville%2CNC-27560&includeNeighborhood=0&include=ciso2&maxResults=20&key=abs')])

In the output, you can see ‘include’, ‘maxResults’ in the string although we haven’t specified any values because they are default values specified in the schema.

build_query_string(data)[source]

This method occurs after dumping the data into the class.

Args:
data (dict): dictionary of all the query values
Returns:
data (dict): ordered dict of all the values

The query string consists of all the values concatenated with ‘&’. As part of the location by query services, the url will be encoded. If the ‘query’ consists of spaces, commas, or other special characters all those will be encoded.

For example:
  • space(‘ ‘) - %20
  • comma(,) - %2C, etc.

Elevations API

class bingmaps.urls.elevations_build_urls.Elevations(extra=None, only=(), exclude=(), prefix='', strict=False, many=False, context=None, load_only=(), dump_only=(), partial=False)[source]

Main class for Elevations API schema

Data Fields:

Variables:
  • version –

    A string containing v and an integer that specifies the version of the Bing Maps REST Services.

    • default: v1
  • restApi –

    A part of the URL path that identifies the REST API.

    • default: ‘Elevation’ (for Elevations API services)
  • resourcePath – A part of the URL path that specifies a resource, such as an address or landmark.

This schema helps in creating the main parameters of all types of elevations API based services (List, Polyline, SeaLevel, Bounds). The above mentioned data fields make up the main parameters of the url.

Example:

The below example can show you a typical example for how the main URL parameters can be passed in as a dictionary

>>> data = {'version': 'v1',
...         'restApi': 'Elevation',
...         'resourcePath': ''}

When you dump an empty dictionary, the class helps you in filling the dictionary with default values. You can see the same behaviour in the below example:

>>> data = {}
>>> schema = Elevations()
>>> schema.dump(data).data
OrderedDict([('version', 'v1'), ('restApi', 'Elevation')])

Note

Elevations class is common for all the elevations based services with the same default data.

Elevations for latitude and longitude coordinates

class bingmaps.urls.elevations_build_urls.Coordinates(extra=None, only=(), exclude=(), prefix='', strict=False, many=False, context=None, load_only=(), dump_only=(), partial=False)[source]

Inherited from Elevations

Schema for query parameters in which all the fields will be in a ordered way. All the fields will be dumped in the same order as mentioned in the schema.

Data Fields for the schema (taken from https://msdn.microsoft.com/en-us/library/jj158961.aspx):

Variables:
  • method[Required] –

    A method for calculating elevations (ex. List/Polyline/SeaLevel/Bounds) - REQUIRED field

    • ‘List’ [default]: Use this for returning elevations for a given pair of coordinates.
  • points[Required] – A set of coordinates on the Earth to use in elevation calculations. The exact use of these points depends on the type of elevation request. A set of latitude and longitude values in WGS84 decimal degrees. If you are requesting elevations or elevation offsets for a set of points, the maximum number of points is 1024. Points should be given as lat1,long1,lat2,long2,latn,longn - REQUIRED field
  • heights[Optional] –

    A string that specifies which sea level model to use to calculate elevation. One of the following values:

    • sealevel [default]: Use the geoid Earth model (EGM2008 2.5’).
    • ellipsoid: Use the ellipsoid Earth model (WGS84).
  • o[Optional] – A string specifying the output as JSON or xml.
  • key[Required] – Bing maps key - REQUIRED field

This schema helps in serializing the data.

Post-Dump:
After dumping the data, build_query_string builds up the queryParameters string. The final value after dumping the data would be a string.

Example:

>>> data = {'method': 'List',
...         'points': [15.5467, 34.5676],
...         'key': 'abs'}
>>> schema = Coordinates()
>>> schema.dump(data).data
OrderedDict([('version', 'v1'), ('restApi', 'Elevation'), ('query', 'List?points=15.5467,34.5676&heights=sealevel&key=abs')])
build_query_string(data)[source]

This method occurs after dumping the data into the class.

Args:
data (dict): dictionary of all the query values
Returns:
data (dict): ordered dict of all the values

Elevations at equally-spaced locations along a polyline path

class bingmaps.urls.elevations_build_urls.Polyline(extra=None, only=(), exclude=(), prefix='', strict=False, many=False, context=None, load_only=(), dump_only=(), partial=False)[source]

Inherited from Elevations

Schema for query parameters in which all the fields will be in a ordered way. All the fields will be dumped in the same order as mentioned in the schema.

Data Fields for the schema (taken from https://msdn.microsoft.com/en-us/library/jj158961.aspx):

Variables:
  • method[Required] –

    A method for calculating elevations (ex. List/Polyline/SeaLevel/Bounds) - REQUIRED field

    • ‘Polyline’ [default]: Use this for returning elevations for a given pair of coordinates.
  • points[Required] – A set of coordinates on the Earth to use in elevation calculations. The exact use of these points depends on the type of elevation request. A set of latitude and longitude values in WGS84 decimal degrees. If you are requesting elevations or elevation offsets for a set of points, the maximum number of points is 1024. Points should be at least 2 pairs of latitudes and longitudes for Polyline method - It should be a minimum total of 4 points for Polyline method. Points should be given as lat1,long1,lat2,long2,latn,longn
  • heights[Optional] –

    A string that specifies which sea level model to use to calculate elevation. One of the following values:

    • sealevel [default]: Use the geoid Earth model (EGM2008 2.5’).
    • ellipsoid: Use the ellipsoid Earth model (WGS84).
  • samples[Required] – Specifies the number of equally-spaced elevation values to provide along a polyline path. A positive integer. The maximum number of samples is 1024.
  • o[Optional] – A string specifying the output as JSON or xml.
  • key[Required] – Bing maps key - REQUIRED field

This schema helps in serializing the data.

Post-Dump:
After dumping the data, build_query_string builds up the queryParameters string. The final value after dumping the data would be a string.

Example:

>>> data = {'method': 'Polyline',
...         'points': [35.89431, -110.72522, 35.89393, -110.72578],
...         'samples': 10,
...         'key': 'abs'}
>>> schema = Polyline()
>>> schema.dump(data).data
OrderedDict([('version', 'v1'), ('restApi', 'Elevation'), ('query', 'Polyline?points=35.89431,-110.72522,35.89393,-110.72578&heights=sealevel&samples=10&key=abs')])
build_query_string(data)[source]

This method occurs after dumping the data into the class.

Args:
data (dict): dictionary of all the query values
Returns:
data (dict): ordered dict of all the values

Get offset at a set of latitude and longitude coordinates

class bingmaps.urls.elevations_build_urls.Offset(extra=None, only=(), exclude=(), prefix='', strict=False, many=False, context=None, load_only=(), dump_only=(), partial=False)[source]

Inherited from Elevations

Schema for query parameters in which all the fields will be in a ordered way. All the fields will be dumped in the same order as mentioned in the schema.

Data Fields for the schema (taken from https://msdn.microsoft.com/en-us/library/jj158961.aspx:

Variables:
  • method[Required] –

    A method for calculating elevations (ex. List/Polyline/SeaLevel/Bounds) - REQUIRED field

    • ‘SeaLevel’ [default]: Use this for returning elevations for a given pair of coordinates.
  • points[Required] – A set of coordinates on the Earth to use in elevation calculations. The exact use of these points depends on the type of elevation request. A set of latitude and longitude values in WGS84 decimal degrees. If you are requesting elevations or elevation offsets for a set of points, the maximum number of points is 1024. Points should be given as lat1,long1,lat2,long2,latn,longn - REQUIRED field
  • o[Optional] – A string specifying the output as JSON or xml.
  • key[Required – Bing maps key - REQUIRED field

This schema helps in serializing the data.

Post-Dump:
After dumping the data, build_query_string builds up the queryParameters string. The final value after dumping the data would be a string.

Example:

>>> data = {'method': 'SeaLevel',
...         'points': [15.5467, 34.5676],
...         'key': 'abs'}
>>> schema = Offset()
>>> schema.dump(data).data
OrderedDict([('version', 'v1'), ('restApi', 'Elevation'), ('query', 'SeaLevel?points=15.5467,34.5676&key=abs')])
build_query_string(data)[source]

This method occurs after dumping the data into the class.

Args:
data (dict): dictionary of all the query values
Returns:
data (dict): ordered dict of all the values

Get elevations within an area on the Earth defined as a bounding box

class bingmaps.urls.elevations_build_urls.BoundingBox(extra=None, only=(), exclude=(), prefix='', strict=False, many=False, context=None, load_only=(), dump_only=(), partial=False)[source]

Inherited from Elevations

Schema for query parameters in which all the fields will be in a ordered way. All the fields will be dumped in the same order as mentioned in the schema.

Data Fields for the schema (taken from https://msdn.microsoft.com/en-us/library/jj158961.aspx:

Variables:
  • method[Required] –

    A method for calculating elevations (ex. List/Polyline/SeaLevel/Bounds) - REQUIRED field

    • ‘Bounds’ [default]: Use this for returning elevations for a given pair of coordinates.
  • bounds[Required] –

    Specifies the rectangular area over which to provide elevation values. A bounding box defined as a set of WGS84 latitudes and longitudes in the following order:

    • south latitude, west longitude, north latitude, east longitude
    • REQUIRED field
  • rows,cols[Required] – Specifies the number of rows and columns to use to divide the bounding box area into a grid. The rows and columns that define the bounding box each count as two (2) of the rows and columns. Elevation values are returned for all vertices of the grid. Integers with a value of two (2) or greater. The number of rows and columns can define a maximum of 1024 locations (rows * cols <= 1024).
  • heights[Optional] –

    A string that specifies which sea level model to use to calculate elevation. One of the following values:

    • sealevel [default]: Use the geoid Earth model (EGM2008 2.5’).
    • ellipsoid: Use the ellipsoid Earth model (WGS84).
  • o[Optional] – A string specifying the output as JSON or xml.
  • key[Required] – Bing maps key

This schema helps in serializing the data.

Post-Dump:
After dumping the data, build_query_string builds up the queryParameters string. The final value after dumping the data would be a string.

Example:

>>> data = {'method': 'Bounds',
...         'bounds': [15.5463, 34.6577, 16.4365, 35.3245],
...         'rows': 4,
...         'cols': 5,
...         'key': 'abs'}
>>> schema = BoundingBox()
>>> schema.dump(data).data
OrderedDict([('version', 'v1'), ('restApi', 'Elevation'), ('query', 'Bounds?bounds=15.5463,34.6577,16.4365,35.3245&rows=4&cols=5&heights=sealevel&key=abs')])
build_query_string(data)[source]

This method occurs after dumping the data into the class.

Args:
data (dict): dictionary of all the query values
Returns:
data (dict): ordered dict of all the values

Traffic Incidents API

class bingmaps.urls.traffic_build_urls.TrafficIncidentsSchema(extra=None, only=(), exclude=(), prefix='', strict=False, many=False, context=None, load_only=(), dump_only=(), partial=False)[source]

Schema for query parameters in which all the fields will be in a ordered way. All the fields will be dumped in the same order as mentioned in the schema.

Data Fields for the schema (taken from https://msdn.microsoft.com/en-us/library/hh441726.aspx):

Variables:
  • mapArea[Required] – A rectangular area specified as a bounding box. The size of the area can be a maximum of 500 km x 500 km. A bounding box defines an area by specifying SouthLatitude, WestLongitude, NorthLatitude, and EastLongitude values.
  • includeLocationCodes[Optional] –

    One of the following values:

    • ‘true’
    • ‘false’ [default]

    If you want to use the default value, you can omit this parameter from the URL request.

  • severity[Optional] –

    One or more of the following integer values:

    • 1: LowImpact
    • 2: Minor
    • 3: Moderate
    • 4: Serious

    The default is to return traffic incidents for all severity levels.

  • type[Optional] –

    One or more of the following integer values:

    • 1: Accident
    • 2: Congestion
    • 3: DisabledVehicle
    • 4: MassTransit
    • 5: Miscellaneous
    • 6: OtherNews
    • 7: PlannedEvent
    • 8: RoadHazard
    • 9: Construction
    • 10: Alert
    • 11: Weather
  • o[Optional] – A string specifying the output as JSON or xml.
  • key[Required] – Bing maps key - REQUIRED field

This schema helps in serializing the data.

Post-Dump:
After dumping the data, build_query_string builds up the queryParameters string. The final value after dumping the data would be a string.

Example:

>>> data = {'mapArea': [37, -105, 45, -94],
...         'includeLocationCodes': 'true',
...         'type': [5],
...         'o': 'xml',
...         'key': 'abs'}
>>> query = TrafficIncidentsSchema()
>>> query.dump(data).data
OrderedDict([('version', 'v1'), ('restApi', 'Traffic'), ('resourcePath', 'Incidents'), ('query', '37.0,-105.0,45.0,-94.0/true?type=5&o=xml&key=abs')])