Bing Spatial Data Services

Contents

Getting Started with the Spatial Data Services ............................................................................ 4

What's New in Bing Spatial Data Services ................................................................................... 6

Public Data Sources ..................................................................................................................... 7

FourthCoffeeSample ................................................................................................................. 8

NAVTEQNA ............................................................................................................................ 10

NAVTEQEU ............................................................................................................................ 11

Traffic Incident Data Source ................................................................................................... 13

POI Entity Types ..................................................................................................................... 20

Status Codes and Error Handling .............................................................................................. 26

Get Job List ................................................................................................................................ 27

Geocode and Data Source Limits .............................................................................................. 34

Geocode Dataflow API ............................................................................................................... 35

Create a Geocode Job and Upload Data ............................................................................... 37

Get Status of a Geocode Job ................................................................................................. 43

Download Geocode Job Results ............................................................................................ 47

Geocode Dataflow Response Description .............................................................................. 51

Geocode Dataflow Walkthrough ............................................................................................. 58

Geocode Dataflow Sample Code ........................................................................................... 67

Geocode Dataflow Data Schema - Version 1.0 ...................................................................... 78

Geocode Dataflow Data Schema - Version 2.0 ...................................................................... 88

Geocode Dataflow Sample Input and Output Data Version 1.0 ........................................... 108

Geocode Dataflow Sample Input and Output Data Version 2.0 ........................................... 117

Entity Types .......................................................................................................................... 131

Data Source Management API ................................................................................................ 142

Load Data Source Dataflow .................................................................................................. 144

Create a Load Data Source Job and Input Entity Data ..................................................... 145

Get Load Data Source Status ........................................................................................... 155

Publish a Staged Data Source .......................................................................................... 162

Load Data Source Dataflow Response Description .......................................................... 168

Load Data Source Data Schema and Sample Input ......................................................... 175

Geography Types .............................................................................................................. 182

Helpful Tips for Entity Data ................................................................................................ 185

Load Data Source Dataflow Sample Code (C#) ............................................................... 186

Load Data Source Dataflow Sample Code (VB) ............................................................... 194

Get Data Source Information ................................................................................................ 201

Download a Data Source Dataflow ....................................................................................... 211

Create a Download Job ..................................................................................................... 212

Get Download Data Source Job Status ............................................................................ 216

Get Downloaded Data ....................................................................................................... 221

Download Data Source Walkthrough ................................................................................ 223

Download Data Source Dataflow Response Description .................................................. 228

Make a Data Source Public .................................................................................................. 235

Get All Public Data Sources ................................................................................................. 238

Rollback a Data Source Dataflow ......................................................................................... 241

Delete a Data Source ........................................................................................................... 248

Query API ................................................................................................................................. 250

Query by Area ....................................................................................................................... 251

Query Near a Route .............................................................................................................. 270

Query by Property ................................................................................................................. 280

Query by ID ........................................................................................................................... 294

Query Options ....................................................................................................................... 304

Query Response Description ................................................................................................ 308

Query API Sample Code (C#) .............................................................................................. 311

Query API Sample Code (VB) .............................................................................................. 318

Geodata API (Preview) ............................................................................................................ 326

Developer Resources ............................................................................................................... 340

Bing Spatial Data Services

The Bing Spatial Data Services Application Programming Interface (API) provides a

Representational State Transfer (REST) interface that can geocode, store and query spatial data.

This simple REST interface accomplishes tasks by setting parameters in a URL and then

submitting the URL as an HTTP request. The HTTP response returns the results of the request.

With the Bing Spatial Data Services, you can:

Geocode and reverse-geocode large numbers of locations with the Geocode Dataflow API.

Store and query entities with a location, such as set of retail stores or restaurants using our

Data Source Management API and Query API.

Bing Maps Account Center (alternative): You can also manage data sources and geocode

using the Bing Maps Account Center. For more information, see Creating and Managing Data

Sources.

Download this documentation: CHM | PDF

Transaction accounting is provided when you use the Bing Spatial Data Services. For more

information about billable and non-billable transactions for the Bing Spatial Data Services, see

Usage Transactions. There are also some use limits for this API. For more information, see

Geocode and Data Source Limits

In this Section

Getting Started with the Spatial Data Services Provides information to help you get started

with the Bing Spatial Data Services.

What's New in Bing Spatial Data Services Outlines the latest features added to the Bing

Spatial Data Services.

Public Data Sources Includes descriptions of public data sources

that you can query.

Status Codes and Error Handling Describes the HTTP errors that can occur when

you use the Bing Spatial Data Services APIs.

Geocode and Data Source Limits Defines limits on the total number of dataflow

and data source jobs, such as the number of

jobs that can be in process at the same time.

Get Job List Describes the API that returns a list of all

dataflow and data source jobs submitted in the

last 15 days.

Geocode Dataflow API Describes the API that geocodes sets of spatial

data.

Data Source Management API Describes the API that creates and manages

data sources.

Query API Describes the API that queries a data source.

You can query for entities in a given area,

along a route, or search by entity property or

ID.

Geodata API (Preview) [This API is a preview and is subject to

change.] Describes the API that gets one or

more polygons that represent a geographical

entity such as a country/region, admin division,

or postal code.

Developer Resources Provides a set of helpful links and references

for the developer.

See Also Terms and Conditions

Getting Started with the Spatial Data Services Bing Spatial Data Services provides REST APIs that work with large sets of spatial data. With

these APIs you can geocode spatial data and you can store data that has a spatial component in

data sources that you can query.

See the links in the How to: sections below to find out more information.

Get started by signing up for a Bing Maps Account and requesting access

To get started with the Bing Spatial Data Services, you must have a Bing Maps Account and a

Bing Maps Key. For more information, see Create a Bing Maps Key.

Before using this API, review the Geocode and Data Source Limits

You can also use Bing Maps Account Center to geocode entities and to create and manage your

data sources. For more information, see Creating and Managing Data Sources. The Bing Spatial

Data Services and the Bing Maps Account Center can be used interchangeably to manage data

sources for a single Bing Maps Account.

How to: Geocode and reverse-geocode spatial data

Use the Geocode Dataflow API to create dataflow jobs that geocode and reverse-geocode large

sets of data. For more information, see Geocode Dataflow API. For an example of the complete

process, see the Geocode Dataflow Walkthrough

How to: Create a data source

Use the Load Data Source Dataflow to create a new data source.

How to: Query a data source

Use the Query API to query for entities in a data source.

How to: Update a data source

Use the Load Data Source Dataflow to update an existing data source.

How to: Download a data source

Use the Download a Data Source Dataflow API to download a data source.

How to: Delete a data source

Use the Delete a Data Source API to delete a data source.

How to: Stage a data source

Use the Load Data Source Dataflow to stage an existing data source. After testing your data

source, you can Publish a Staged Data Source.

How to: Rollback a data source

Use the Rollback a Data Source Dataflow to rollback a data source to a previous version.

How to: Get information about data sources

Use the Get Data Source Information API to get information about a data source such as the

entity type and properties that it stores. You can also request information about all of the data

sources that belong to a Bing Maps Account.

How to: Use the Spatial Data Services with other Bing Maps APIs

Read the Show Spatial Data Search Results on a Map and Searching for Traffic Incidents Along

a Route articles to learn how integrate Bing Spatial Data Services with Bing Maps Rest Services

and the Bing Maps AJAX Control, Version 7.0.

Public Data Sources

The following are public data sources that you can access with any Bing Maps Key.

NAVTEQNA NavTechNA is a data source that contains

points of interest in North America.

NAVTEQEU NavTechEU is a data source that contains

points of interest in Europe.

Traffic Incident Data Source TrafficIncident is a data source that contains

traffic incidents data in the United States and

Canada.

FourthCoffeeSample FourthCoffeeSample is a data source with

sample data.

Transaction Accounting

Transactions are counted for each Bing Spatial Data Services request sent with a valid Bing

Maps Key. For information about billable and non-billable transactions for the Bing Spatial Data

Services and how to view them, see Viewing Bing Maps Usage Reports.

What's New in Bing Spatial Data Services The Bing Spatial Data Services contains the following new features.

November 2013

Use geographical shapes, such as polygons and line strings, to represent entity locations

in your data source data schema

You can now define location as either a geographical area, such as polygon or line string or a

single point (latitude and longitude). For more information, see Load Data Source Data Schema

and Sample Input and Geography Types.

Note that geographical shapes are only supported when you upload your data source using the

Bing Spatial Data Services. You cannot use the Bing Maps Account Center to upload data

sources with a geographical shape type.

Use geographical shapes to query data sources.

You can use the Geography Types to query for data source entities within a custom area defined

by geographical shapes using the intersects spatial filter function. For more information, see

Query by Area. If you want to return the intersection of an entitys geographical shape with

another geographical shape you specify, use the intersection function with the $select query

option.

Get a list of all public data sources. You can request a list of all publicly available data sources.

This includes the Public Data Sources owned and managed by Microsoft as well as any data

source that is made public using the Make a Data Source Public API.

Search up to 1000 kilometers when you Query by Area or Query by Property. The previous

limit was 400 kilometers. .

June 2013

GeoData API (Preview) gets geographical boundaries. With the Geodata API (Preview), you

can get boundary data for a variety of geographical entities from a country or region to postal

codes by specifying an address or point (latitude and longitude) inside the entity.

May, 2013

Batch geocoding and data source APIs are now available to all users. Previously only

available to enterprise users, the Geocode Dataflow API and Data Source Management API are

now accessible to any user with a Bing Maps Account. Usage is subject to the Geocode and Data

Source Limits.

March, 2013

Query for entities around an address. When you query a data source for entities near a

location (Query by Area), you can now specify an address string for the center point of your

search.

Stage a data source before publishing. To stage and query data source data before you

publish it, set the loadOperation parameter to completeStaging or incrementalStaging when

you Create a Load Data Source Job and Input Entity Data. You can query the staged data source

by setting the isStaging parameter to 1 or true in your query. When you are ready to publish the

data source, use the $commit URL described in Publish a Staged Data Source. Staged data

sources that are not published are deleted after 30 days.

Rollback a data source to a previous version. You can Rollback a Data Source Dataflow to a

previous version of the entity data and schema. Up to two (2) previous versions are kept. You can

get a list of previous versions and query for the schema (metadata) for those versions using the

Get Data Source Information URLs.

Download previous or staged data source versions. You can download previous versions and

the staged version of a data source using the job ID associated with that version. To get job IDs,

see Get Data Source Information. For download details, see Create a Download Job.

Delete a staged data source. You can delete a staged data source by setting the isStaging

parameter to 1 or true when you Delete a Data Source.

January, 2013

View a list of all dataflow and data source jobs submitted in the last 15 days. You can now

request a list of all Geocode Dataflow API and Data Source Management API jobs that you

submitted in the last 15 days. Pending jobs are listed first.

Request __Distance values with bounding box queries. . When you query for entities within a

bounding box, you can return the distance from the center of the bounding box by adding

__Distance to the $select query option. You can also sort bounding box query results by this

distance when you set the $orderby parameter to __Distance.

Use "$select=*,__Distance" to return all entity properties and the distance to the entity

property when you Query by Area.

Public Data Sources The Bing Spatial Data Services provide the following public data sources for your use. You can

query these data sources with any Bing Maps Key.

You can also make any data source associated with your Bing Maps Account public. For more

information, see Make a Data Source Public.

Data Source Description

FourthCoffeeSample This data source contains sample data. The

examples provided in the Query API

documentation use this data source.

NAVTEQNA This data source contains points of interest for

North America.

NAVTEQEU This data source contains points of interest for

Europe.

Traffic Incident Data Source This data source contains traffic incident data

that you can use to query for traffic incidents in

Data Source Description

an area by using the Query by Area API.

For the list of Standard Industry Code (SIC) entity type IDs that you can query for the

NAVTEQNA and NAVTEQEU data sources, see POI Entity Types.

FourthCoffeeSample

The FourthCoffeeSample data source is a sample data source that you can use to learn how to

query and get data source information by using the Bing Spatial Data Services.

All Query API transactions are billable transactions including queries to the

FourthCoffeeSample data source. Therefore, you may want to create an evaluation

account to use with this data source. For more information about how to create an

evaluation account, see Getting a Bing Maps Key.

Entity Properties

The following table describes the properties that you can query. These properties make up the

FourthCoffeeShops entity type that is used by the FourthCoffeeSample data source.

Property Data Type Example Value

EntityID (Primary Key) Edm.String -18147

Latitude Edm.Double 50.792458

Longitude Edm.Double -1.146712

AddressLine Edm.String Bury Road

PrimaryCity Edm.String Alverstoke

SecondaryCity Edm.String Gosport

Subdivision Edm.String Hampshire

CountryRegion Edm.String United Kingdom

PostalCode Edm.String PO123

Phone Edm.String 800-555-0111

Manager Edm.String Aaron Con

StoreOpen Edm.String Y

StoreType Edm.String Kiosk


Name Edm.String Fourth Coffee Store #18147

DisplayName Edm.String Fourth Coffee Store #18147,

Alverstoke, Hampshire,

United Kingdom

IsWiFiHotSpot Edm.Boolean 0 [false]

SeatingCapacity Edm.Int64 50

IsWheelChairAccessible Edm.Boolean 1 [true]

AcceptsOnlineOrders Edm.Boolean 0 [false]

AcceptsCoffeeCards Edm.Boolean 1 [true]

Open Edm.Int64 800

Close Edm.Int64 2200

CreatedDate Edm.DateTime 2010-11-10T17:19:36

LastUpdatedDate Edm.DateTime 2010-11-15T17:19:36

How to query the FourthCoffeeSample data source

You can query FourthCoffeeShops entities in the FourthCoffeeSample data source by using the

following base URL and adding additional parameters such a geographical area to search and

the properties you want to return.

Base Query URL

http://spatial.virtualearth.net/REST/v1/data/20181f26d9e94c81acdf9496133d4f23/FourthCoffe

eSample/FourthCoffeeShops

Query Example

The following query example queries for FourthCoffeeShops entities within 5 kilometers of a

location that is specified as a latitude and longitude pair. Because this is a sample data source,

the query key you use can be any Bing Maps Key. For more information, see Query API.

http://spatial.virtualearth.net/REST/v1/data/20181f26d9e94c81acdf9496133d4f23/FourthCoffe

eSample/FourthCoffeeShops?spatialFilter=nearby(40.83274904439099,-

74.3163299560546935,5)&$select=EntityID,Latitude,Longitude,__Distance&$top=3&key=anyBingM

apsKey

NAVTEQNA

The NAVTEQNA data source contains information about points of interest (POIs) in North

America. You can query this data source by using the Bing Spatial Data Services Query API and

any Bing Maps Key.

When you query this data source for specific property values, you must include a

geographical area to search. This does not apply if you are querying for specific entities

using entity ID. See Query by Area and Query by ID for details. POI entities may not be

available for every location.

POI Entity Properties

The following table describes the properties that you can query to get information about a point of

interest in North America. These properties make up the NAVTEQPOIs entity type that is used by

the NAVTEQNA data source.


EntityID (Primary Key) Edm.String 111

Name Edm.String Coho Vineyard & Winery

DisplayName Edm.String Coho Vineyard & Winery



AddressLine Edm.String 1234 Main Street

Locality Edm.String Helena

AdminDistrict Edm.String Montana

AdminDistrict2 Edm.String Lewis and Clark

PostalCode Edm.String 98146

CountryRegion Edm.String USA

Phone Edm.String 800-5550111

EntityTypeID Edm.String 2084

Entity Types

For a complete list of the entity type IDs that you can query, see POI Entity Types.

How to query the NAVTEQNA data source

You can query NAVTEQNA data source by using the following base URL and adding additional

parameters such a geographical area to search and the properties you want to return. For a

complete description of query options and more examples, see Query API.

When you query this data source for specify property values, you must include a


using entity ID. See Query by Area and Query by ID for details.

Base Query URL

http://spatial.virtualearth.net/REST/v1/data/f22876ec257b474b82fe2ffcb8393150/NavteqNA/Na

vteqPOIs

Query Example

The following query example queries for banks within 5 kilometers of the specified latitude and

longitude. The query key you use can be any Bing Maps Key. For complete information about

querying a data source, see Query API.

http://spatial.virtualearth.net/REST/v1/data/f22876ec257b474b82fe2ffcb8393150/NavteqNA/Na

vteqPOIs?spatialFilter=nearby(40.83274904439099,-

74.3163299560546935,5)&$filter=EntityTypeID%20eq%20'6000'&$select=EntityID,DisplayName,La

titude,Longitude,__Distance&$top=3&key=anyBingMapsKey

NAVTEQEU

The NAVTEQEU data source contains information about points of interest (POIs) in Europe. You

can query this data source by using the Bing Spatial Data Services Query API and any Bing

Maps Key.

When you query this data source for specific property values, you must include a


using entity ID. See Query by Area and Query by ID for details. POI entities may not be

available for every location.

POI Entity Properties

The following table describes the properties that you can query to get information about a point of

interest. These properties make up the NAVTEQPOIs entity type that is used by the NAVTEQEU

data source.


EntityID (Primary Key) Edm.String 111


LanguageCode Edm.String GER

Name Edm.String Contoso, Ltd

DisplayName Edm.String Contoso, Ltd



AddressLine Edm.String Calle Rodriguez, 1234

Locality Edm.String Malaga

AdminDistrict Edm.String Andalucia

AdminDistrict2 Edm.String MA

PostalCode Edm.String 28146

CountryRegion Edm.String Espaa

Phone Edm.String +34 xx xxx xxxx

EntityTypeID Edm.String 3000

Entity Types

For a complete list of the entity type IDs that you can query, see POI Entity Types.

How to query the NAVTEQEU data source

You can query the NAVTEQEU data source by using the following base URL and adding

additional parameters such a geographical area to search and the properties you want to return.

For a complete description of query options and more examples, see Query API.

Base Query URL

http://spatial.virtualearth.net/REST/v1/data/c2ae584bbccc4916a0acf75d1e6947b4/NavteqEU/Na

vteqPOIs

Query Example

The following query example queries for banks within 5 kilometers of the specified latitude and

longitude. The query key you use can be any Bing Maps Key.

http://spatial.virtualearth.net/REST/v1/data/c2ae584bbccc4916a0acf75d1e6947b4/NavteqEU/Na

vteqPOIs?spatialFilter=nearby(50.1120796203613,8.68340969085693,100)&$select=EntityID,Lat

itude,Longitude,DisplayName,__Distance,LanguageCode&$top=3&key=anyBingMapsKey

Traffic Incident Data Source

The TrafficIncident data source contains information traffic incidents. You can query for traffic

incidents in a specified area by using the Bing Spatial Data Services Query by Area API and the

Query Near a Route API and any Bing Maps Key.

Traffic Incident Properties

The following table describes the information provided for a traffic incident.

Property Data Type Description and Values

IncidentId Edm.String A unique ID for the incident.

Example: 210546697

Latitude Edm.Double The latitude of the incident.

Example: 38.64829

Longitude Edm.Double The longitude of the incident.

Example: -94.36405

LastModifiedUTC Edm.DateTime The time the incident

information was last updated

specified as a Coordinated

Universal Time (UTC) time.

Example: 2011-12-

05T17:18:21.67Z

StartTimeUTC Edm.DateTime The time the incident occurred

specified as a Coordinated

Universal Time (UTC) time..

Example: 2011-12-

05T17:16:00Z

EndTimeUTC Edm.DateTime The time that the traffic incident

will end specified as a

Coordinated Universal Time

(UTC).

Example: 2011-12-

05T17:46:00Z

Type Edm.String The type of incident specified

by one of the following values.

Accident

Congestion


DisabledVehicle

MassTransit

Miscellaneous

OtherNews

PlannedEvent

RoadHazard

Construction

Alert

Weather

Example: Accident

Severity Edm.String The level of importance of

incident specified by one of the

following values.

LowImpact

Minor

Moderate

Serious

Example: Minor

Verified Edm.Boolean A value of true indicates that

the incident has been visually

verified or otherwise officially

confirmed by a source like the

local police department.

Example: true

RoadClosed Edm.Boolean A value of true indicates that

there is a road closure.

Example: false

Description Edm.String A description of the incident.

Examples:

W 95th St between Switzer

Rd and Bluejacket Dr -

construction

WB Johnson Dr at I-435 -

bridge repair

DetourInfo Edm.String A description of a detour.

Examples:


Take 63rd St to Roe Ave

and head south to 67th St

take US-40 to Blue Ridge

Cut-Off

LaneInfo Edm.String A description specific to lanes,

such as lane closures.

Examples:

All lanes blocked

Left lane blocked

CongestionInfo Edm.String A description of the congestion.

Examples:

generally slow

sluggish

ToPointLatitude Edm.Double The latitude of the point that

specifies the end of a traffic

incident, such as the end of a

construction zone.

Example: 38.65831

ToPointLongitude Edm.Double The longitude of the point that

specifies the end of a traffic

incident, such as the end of a

construction zone.

Example: -94.36706

How to query the TrafficIncidents data source

You can query the TrafficIncidents data source by using the following base URL and specifying

an area to search by using the Query by Area API or the Query Near a Route API.

Base Query URL

http://spatial.virtualearth.net/REST/v1/data/8F77935E46704C718E45F52D0D5550A6/TrafficInci

dents/TrafficIncident

Query Example

The following query example queries for traffic incidents along a route from Houston, Texas to

Galveston, Texas by using the Query Near a Route API. The query key you use can be any Bing

Maps Key.

http://spatial.virtualearth.net/REST/v1/data/8F77935E46704C718E45F52D0D5550A6/TrafficInci

dents/TrafficIncident?spatialFilter=nearRoute('Houston,TX','Galveston,Tx')&key=anyBingMap

sKey

XML Response

This request returns traffic incident information in the following format.

uuid:e767cc8a-6932-4ec1-9b78-d2c36aa81989;id=45353

2012 Microsoft and its suppliers. This API and any results

cannot be used or accessed without Microsoft's express written permission.

2012-02-01T19:08:15Z

https://spatial.virtualearth.net/REST/v1/data/8f77935e46704c718e45f52d0d5550a6/Traffi

cIncidents/TrafficIncident('277303858')

2012-02-01T19:08:15Z

277303858

29.378040

-95.020810

2012-01-25T14:29:02.01Z

2011-10-17T12:00:00Z

2012-02-12T14:00:00Z

Construction

Minor

true

true

FM-1765 is closed in both directions between Delaney Rd to FM-2004

- construction

follow the posted signage

0

0

https://spatial.virtualearth.net/REST/v1/data/8f77935e46704c718e45f52d0d5550a6/Traffi

cIncidents/TrafficIncident('277303880')

2012-02-01T19:08:15Z

277303880

29.769700

-95.358560

2012-01-25T14:29:02.01Z

2011-08-08T11:54:00Z

2012-10-01T22:00:00Z

Construction

Minor

true

true

N Main St is closed in both directions between Naylor St and

Franklin St - construction

Follow posted signage

0

0

JSON Response

When you specify $format=json in the URL, the response returns traffic incident information in the

following JSON format.

{

"d":{

"__copyright":"\u00a9 2012 Microsoft and its suppliers. This API and any results

cannot be used or accessed without Microsoft's express written permission.",

"results":[

{

"__metadata":{

"uri":"https:\/\/spatial.virtualearth.net\/REST\/v1\/data\/8f77935e46704c718e45f52d0d5550

a6\/TrafficIncidents\/TrafficIncident('277303858')"

},

"IncidentId":"277303858",

"Latitude":29.378040,

"Longitude":-95.020810,

"LastModifiedUTC":"2012-01-25T14:29:02.01Z",

"StartTimeUTC":"2011-10-17T12:00:00Z",

"EndTimeUTC":"2012-02-12T14:00:00Z",

"Type":"Construction",

"Severity":"Minor",

"Verified":"true",

"RoadClosed":"true",

"Description":"FM-1765 is closed in both directions between Delaney Rd to FM-

2004 - construction",

"DetourInfo":"follow the posted signage",

"LaneInfo":"",

"CongestionInfo":"",

"ToPointLatitude":0,

"ToPointLongitude":0,

"LocationCodes":""

},

{

"__metadata":{

"uri":"https:\/\/spatial.virtualearth.net\/REST\/v1\/data\/8f77935e46704c718e45f52d0d5550

a6\/TrafficIncidents\/TrafficIncident('277303880')"

},

"IncidentId":"277303880",

"Latitude":29.769700,

"Longitude":-95.358560,

"LastModifiedUTC":"2012-01-25T14:29:02.01Z",

"StartTimeUTC":"2011-08-08T11:54:00Z",

"EndTimeUTC":"2012-10-01T22:00:00Z",

"Type":"Construction",

"Severity":"Minor",

"Verified":"true",

"RoadClosed":"true",

"Description":"N Main St is closed in both directions between Naylor St and

Franklin St - construction",

"DetourInfo":"Follow posted signage",

"LaneInfo":"",

"CongestionInfo":"",

"ToPointLatitude":0,

"ToPointLongitude":0,

"LocationCodes":""

}

]

}

}

POI Entity Types

The following table shows the Standard Industry Code (SIC) entity IDs that are returned by the

NAVTEQNA and NAVTEQEU data sources. POI entities may not be available for every location.

Entity Type ID Entity Type Name

2084 Winery

3578 ATM

4013 Train Station

4100 Commuter Rail Station

4170 Bus Station

4444 Named Place

4482 Ferry Terminal

4493 Marina

4580 Public Sports Airport

4581 Airport

5000 Business Facility

5400 Grocery Store

5511 Auto Dealerships

5512 Auto Dealership-Used Cars

5540 Petrol/Gasoline Station

5571 Motorcycle Dealership

5800 Restaurant

5813 Nightlife

5999 Historical Monument

6000 Bank

6512 Shopping


7011 Hotel

7012 Ski Resort

7013 Other Accommodation

7014 Ski Lift

7389 Tourist Information

7510 Rental Car Agency

7520 Parking Lot

7521 Parking Garage/House

7522 Park & Ride

7538 Auto Service & Maintenance

7832 Cinema

7897 Rest Area

7929 Performing Arts

7933 Bowling Centre

7940 Sports Complex

7947 Park/Recreation Area

7985 Casino

7990 Convention/Exhibition Centre

7992 Golf Course

7994 Civic/Community Centre

7996 Amusement Park

7997 Sports Centre

7998 Ice Skating Rink

7999 Tourist Attraction

8060 Hospital

8200 Higher Education

8211 School

8231 Library


8410 Museum

8699 Automobile Club

9121 City Hall

9211 Court House

9221 Police Station

9500 Business Service

9501 Other Communication

9502 Telephone Service

9503 Cleaning & Laundry

9504 Hair & Beauty

9505 Health Care Service

9506 Mover

9507 Photography

9508 Video & Game Rental

9509 Storage

9510 Tailor & Alteration

9511 Tax Service

9512 Repair Service

9513 Retirement/Nursing Home

9514 Social Service

9515 Utilities

9516 Waste & Sanitary

9517 Campground

9518 Auto Parts

9519 Car Wash/Detailing

9520 Local Transit

9521 Travel Agent & Ticketing

9522 Truck Stop/Plaza


9523 Church

9524 Synagogue

9525 Government Office

9527 Fire Department

9528 Road Assistance

9529 Funeral Director

9530 Post Office

9531 Banquet Hall

9532 Bar or Pub

9533 Cocktail Lounge

9534 Night Club

9535 Convenience Store

9536 Specialty Food Store

9537 Clothing Store

9538 Men's Apparel

9539 Shoe Store

9540 Specialty Clothing Store

9541 Women's Apparel

9542 Check Cashing Service

9543 Currency Exchange

9544 Money Transferring Service

9545 Department Store

9546 Discount Store

9547 Other General Merchandise

9548 Variety Store

9549 Garden Center

9550 Glass & Window

9551 Hardware Store


9552 Home Center

9553 Lumber

9554 Other House & Garden

9555 Paint

9556 Entertainment Electronics

9557 Floor & Carpet

9558 Furniture Store

9559 Major Appliance

9560 Home Specialty Store

9561 Computer & Software

9562 Flowers & Jewelry

9563 Gift, Antique, & Art

9564 Optical

9565 Pharmacy

9566 Record, CD, & Video

9567 Specialty Store

9568 Sporting Goods Store

9569 Wine & Liquor

9570 Boating

9571 Theater

9572 Race Track

9573 Golf Practice Range

9574 Health Club

9575 Bowling Alley

9576 Sports Activities

9577 Recreation Center

9578 Attorney

9579 Dentist


9580 Physician

9581 Realtor

9582 RV Park

9583 Medical Service

9584 Police Service

9585 Veterinarian Service

9586 Sporting & Instructional Camp

9587 Agricultural Product Market

9589 Public Restroom

9590 Residential Area/Building

9591 Cemetery

9592 Highway Exit

9593 Transportation Service

9594 Lottery Booth

9707 Public Transit Stop

9708 Public Transit Access

9709 Neighborhood

9710 Weigh Station

9714 Cargo Centre

9715 Military Base

9717 Tollbooth (China/Korea)

9718 Animal Park

9719 Truck Dealership

9720 Truck Parking

9986 Home Improvement & Hardware Store

9987 Consumer Electronics Store

9988 Office Supply & Services Store

9989 Taxi Stand


9990 Premium Default

9991 Industrial Zone

9992 Place of Worship

9993 Embassy

9994 County Council

9995 Bookstore

9996 Coffee Shop

9998 Hamlet

9999 Border Crossing

Status Codes and Error Handling Each response to a request provides an HTTP status code. This article describes these codes.

HTTP Status Codes

The following table lists the most common HTTP status codes. Additional information may be

provided with a specific request.

HTTP Status Code Description Details

200 OK The request is successful.

201 Created A new resource is created.

202 Accepted The request has been accepted

for processing.

400 Bad Request The request contained an error.

401 Unauthorized Access was denied. You may

have entered your credentials

incorrectly, or you might not

have access to the requested

resource or operation.

403 Forbidden The request is for something

forbidden. Authorization will not

help.

HTTP Status Code Description Details

404 Not Found The requested resource was

not found.

500 Internal Server Error Your request could not be

completed because there was a

problem with the service.

503 Service Unavailable There's a problem with the

service right now. Please try

again later.

Get Job List Use the following URL to get a list of all dataflow and data source jobs that were submitted in the

last 15 days for the account associated with the Bing Maps Key specified in the request. Jobs are

created when you geocode entities and create or modify a data source. Both pending and

completed jobs are returned with pending jobs listed first. Note that download jobs are not

included in this list.

Some data source processes may include more than one jobs. For example, if you stage a data

source and then publish it, you will have run both a DataSourceIncrementalStaging joband a

DataSourcePublishFromStaged job. This is important because there are limits to the number of

jobs you can run in a given time period. For more information about job limits and other API

requirements, see Geocode and Data Source Limits.

URL Template

http://spatial.virtualearth.net/REST/v1/dataflows/listjobs?key=AccountBingMapsKey&output=

output

Template Parameters

Parameter Alias Description Values

key Required. A

Bing Maps Key

associated with

the Bing Maps

Account that you

want to query.

A Bing Maps Key obtained from the Bing Maps

Account Center that is associated with the

account you want to query. For information

about how to get a Bing Maps Key, see

Getting a Bing Maps Key.

Example:

key=abc123def456ghi789abc123def456ghi789


output o Optional. The

output format for

the response.

One of the following values:

json [default]

xml

Example: output=xml

Response

The response to a get job list request returns information about the following jobs. Job creation

and job completed times are provided as well as the status (Pending or Completed). Note that

Data Source Download Dataflow jobs are not returned by the API.

Jobs marked with an asterisk (*) are also created when you use the Bing Maps Account Center to

manage your data sources.

Job Type Description

Geocode* Geocode Dataflow Job

DataSourceComplete* Load Data Source Dataflow Job to create or to

completely overwrite a data source.

DataSourceIncremental* Load Data Source Dataflow Job to

incrementally update selected entities in a data

source.

DataSourceCompleteStaging Load Data Source Dataflow Job that stages an

update to a data source that creates or

overwrites the data source.

DataSourceIncrementalStaging Load Data Source Dataflow Job that stages an

incremental update to a data source.

DataSourcePublishFromStaged Data Source Publish Job that publishes a

staged data source.

DataSourceRollback Data Source Rollback Dataflow job that

restores a previous version of the data source.

DataSourceDelete* Data Source Delete Job that deletes a data

source.

DataSourceAccess* Make a Data Source Public or Private Job to

specify whether the data source can be

accessed with any Bing Maps Key (public).

Example

Get a list of all dataflow and data source jobs that were submitted in the last 15 days.

http://spatial.virtualearth.net/REST/v1/Dataflows/ListJobs?key=BingMapsKey

JSON Response

This example returns the following response that lists all the pending and completed jobs from the

last 15 days.

{

"authenticationResultCode":"ValidCredentials",

"brandLogoUri":"http:\/\/spatial.virtualearth.net\/Branding\/logo_powered_by.png",

"copyright":"Copyright 2013 Microsoft and its suppliers. All rights reserved. This

API cannot be accessed and the content and any results may not be used, reproduced or

transmitted in any manner without express written permission from Microsoft

Corporation.",

"resourceSets":[

{

"estimatedTotal":110,

"resources":[

{

"__type":"DataServiceJob:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",

"id":"0deea07139a742e7a03a74bb4784a738",

"name":"DeleteADataSource

"createdDate":"Fri, 04 Jan 2013 01:06:23 GMT",

"description":"DataSourceDelete",

"status":"Pending"

},

{

"__type":"DataflowJob:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",

"id":"28217d5f12744c33be7d09f6bce76eb3",

"name":"CreateOrUpdateADataSource",

"completedDate":"Thu, 03 Jan 2013 23:22:15 GMT",

"createdDate":"Thu, 03 Jan 2013 23:21:58 GMT",

"description":"DataSourceComplete",

"failedEntityCount":0,

"processedEntityCount":3,

"status":"Completed",

"totalEntityCount":3

},

{


"id":"47e6703c22d34df98d48674b803f17cb",

"links":[

{

"role":"self",

"url":"https:\/\/spatial.virtualearth.net\/REST\/v1\/dataflows\/Geocode\/47e6703c22d34df9

8d48674b803f22cb"

},

{

"name":"succeeded",

"role":"output",

"url":"https:\/\/spatial.virtualearth.net\/REST\/v1\/dataflows\/ListJobs\/47e6703c22d34df

98d48674b803f22cb\/output\/succeeded"

}

],

"completedDate":"Wed, 02 Jan 2013 23:32:27 GMT",

"createdDate":"Wed, 02 Jan 2013 23:32:24 GMT",

"description":"Geocode",





},

{


"id":"82876e0717114bc1ad2b94e9111e4206",

"name":"IncrementalUpdateOfDataSource",

"completedDate":"Thu, 20 Dec 2012 19:23:19 GMT",

"createdDate":"Thu, 20 Dec 2012 19:23:08 GMT",

"description":"DataSourceIncremental",





},

{

"__type":"DataServiceJob:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",

"id":"9a25a8b26e9c4d569ebfee76ea940160",

"links":[

{

"name":"service",

"role":"dataSource",

"url":"https:\/\/spatial.virtualearth.net\/REST\/v1\/data\/c589f4fb424048428d602ff6cd0a49

eb\/SetDataSourcePublicOrPrivate"

}

],

"name":"SetDataSourcePublicOrPrivate ",

"completedDate":"Thu, 20 Dec 2012 19:15:36 GMT",

"createdDate":"Thu, 20 Dec 2012 19:14:33 GMT",

"description":"DataSourceAccess",

"status":"Completed"

}

]

}

],

"statusCode":200,

"statusDescription":"OK",

"traceId":"3f3b4619b0b7485a97feb883eb871f70"

}

XML Response

This XML response is returned when output=xml is added to the URL.

Copyright 2013 Microsoft and its suppliers. All rights reserved. This API

cannot be accessed and the content and any results may not be used, reproduced or

transmitted in any manner without express written permission from Microsoft

Corporation.

http://spatial.virtualearth.net/Branding/logo_powered_by.png

200

OK

ValidCredentials

f8e999a06f3b449894c175aded847e12

110

DeleteADataSource

0deea07139a742e7a03a74bb4784a738

DataSourceDelete

Pending

2013-01-03T17:06:23.546903-08:00

CreateOrUpdateADataSource

28217d5f12744c33be7d09f6bce76eb3

DataSourceComplete

Completed

2013-01-03T15:21:58.2262338-08:00

2013-01-03T15:22:15.7979398-08:00

3

3

0

47e6703c22d34df98d48674b803f17cb

https://spatial.virtualearth.net/REST/v1/dataflows/Geocode/47e6703c22d34df98d

48674b803f22cb

https://spatial.virtualearth.net/REST/v1/dataflows/ListJobs/47e6703c22d3

4df98d48674b803f22cb/output/succeeded

Geocode

Completed

2013-01-02T15:32:24.1743172-08:00

2013-01-02T15:32:27.1934569-08:00

1234

1234

0

IncrementalUpdateOfDataSource

82876e0717114bc1ad2b94e9111e4206

DataSourceIncremental

Completed

2012-12-20T11:23:08.6682264-08:00

2012-12-20T11:23:19.7245133-08:00

4321

4321

0

SetDataSourcePublicOrPrivate

9a25a8b26e9c4d569ebfee76ea940160

https://spatial.virtualearth.net/REST/v1/data/c589f4fb424048428d602ff6cd0a

22eb/ SetDataSourcePublicOrPrivate

DataSourceAccess

Completed

2012-12-20T11:14:33.2400466-08:00

2012-12-20T11:15:36.5972052-08:00

Geocode and Data Source Limits This topic describes account limits for a Bing Maps Account when you use the Bing Spatial Data

Services or the Bing Maps Account Center to geocode entities and manage data sources.

When you geocode entities or perform data source actions such as creating or updating a data

source using either the Bing Spatial Data Services or the Bing Maps Account Center, a job is

created to perform the action. See Get Job List for a list of jobs that count towards the following

limits.

Account Limits for Basic and Trial Keys

Applicable data source and geocode jobs (see the list of applicable jobs in Get Job List ) that

use Basic or Trial keys from the same Bing Maps Account have the following account limits:

You can have a total of 2 jobs in process at the same time.

You can run a total of 5 jobs in a 24 hour period.

You can have a maximum of 5 data sources per Bing Maps Account.

Data that is geocoded or uploaded to a data source must use UTF-8 encoding, and can have

a maximum of 50 entities. Compressed data files are accepted.

You can download geocode results for up to 14 calendar days after a geocode job completes.

Account Limits for Enterprise Keys [Enterprise Account]

Applicable data source and geocode jobs (see the list of applicable jobs in Get Job List ) that

use Enterprise keys from the same Bing Maps Account have the following account limits.

Jobs that use Basic or Trial keys that belong to an Enterprise account have the limits

described above and are also included in the following limits.

You can have a total of 10 jobs in process at the same time. This limit also includes jobs

run with Basic and Trial keys.

You can run a total of 50 jobs in a 24 hour period. This limit also includes jobs run with

Basic and Trial keys.

You can have a maximum of 25 data sources per Bing Maps Account.

Data that is geocoded or uploaded to a data source must use UTF-8 encoding, and can have

up to 300 MB of uncompressed data and a maximum of 200,000 entities. Compressed data

files are accepted, but the uncompressed limit applies.

You can download geocode results for up to 14 calendar days after a geocode job completes.

View My Jobs

To get a list of all pending and completed jobs within the last 15 days, see Get Job List.

A job is in process until the status is set to "Completed" or "Aborted".

Geocode Dataflow API Before using this API, make sure you are aware of the Geocode and Data Source Limits.

About data schema versions: There are two versions of the input and output data schema for

this API. The latest data schema (version 2.0) provides additional geocoding information in the

response, such as different points for routing and display and a rectangular area that bounds the

location. If you are a new user, version 2.0 is recommended because it provides the greatest

flexibility. Version 1.0 users can upgrade to version 2.0, but must be aware of the changes in the

data schema including some name changes that were made to match the REST Services

Locations API.

The Geocode Dataflow API uses REST URLS to geocode and reverse-geocode large sets of

spatial data. To use this API, you must:

1. Format your location data using the Geocode Dataflow Data Schema - Version 2.0 or

Geocode Dataflow Data Schema - Version 1.0 (for existing users). The spatial data you

upload can be in XML format, or it can be provided as sets of values that use commas, tabs,

or pipe (|) characters to separate the values.

2. Create a Geocode Job and Upload Data

3. Get Status of a Geocode Job and watch for the job to complete.

4. Download Geocode Job Results

For an overview of this process, see Geocode Dataflow Walkthrough.

To get a list of all geocode dataflow jobs and data source jobs submitted in the last 15 days, see

Get Job List.

In this Section

Create a Geocode Job and Upload Data Describes how to create a job to geocode and

reverse-geocode the data.

Get Status of a Geocode Job Describes how to get the status of a geocode

job.

Download Geocode Job Results Describes how to download geocoded results.

Geocode Dataflow Response Description Describes the information returned in the HTTP

responses.

Geocode Dataflow Walkthrough Provides a detailed overview of how to use the

Geocode Dataflow using version 2.0 of the data

schema.

Geocode Dataflow Sample Code Provides complete sample code that uses the

Geocode Dataflow and version 1.0 of the data

schema to geocode data.

Geocode Dataflow Data Schema - Version 1.0 Describes the original (version 1.0) data

schema for the input data and the geocoded

results.

Geocode Dataflow Data Schema - Version 2.0 Describes version 2.0 of the data schema for

the input data and the geocoded results.

Geocode Dataflow Sample Input and Output

Data Version 1.0

Shows examples of all types of accepted input

formats for the original (version 1.0) of the data

schema. This includes XML examples and

examples of sets of values separated by pipe

(|), comma, or tab characters

Geocode Dataflow Sample Input and Output

Data Version 2.0

Shows examples of all types of accepted input

formats for version 2.0 of the data schema.

This includes XML examples and examples of

sets of values separated by pipe (|), comma, or

tab characters

Entity Types Provides a list of supported entity types.

Create a Geocode Job and Upload Data

Use the following URL to upload a set of spatial data and to create a job to geocode and reverse-

geocode the data.

Supported HTTP Methods

POST

URL template

This template supports both HTTP and HTTPS protocols. URLs in the response use

HTTPS protocol.

A job is created when you geocode entity data. Before using this API, review the job limits in

Geocode and Data Source Limits.

Upload locations and points and create a geocode job.

The data that you upload can contain both data to geocode and data to reverse geocode. The

geocode process detects the type of data for each entry and performs the appropriate action.

http://spatial.virtualearth.net/REST/v1/Dataflows/Geocode?input=input&output=output&dataL

ocation=dataLocation&key=BingMapsKey

Template Parameters

Parameter names and values are not case-sensitive except for the key parameter value.

Parameter Alia

s

Description Values

dataLocati

on

Optional.

Specifies the

location of the

data to download.

You must

set the

dataLocati

on

parameter

to the

location of

the data

A Windows Azure Blob Service REST API location that

contains the data to process. The data must be in XML

format. The Blob Service REST API uses the following

URL formats:

http://account-name.blob.core.windows.net/myDataFile

https://account-name.blob.core.windows.net/myDataFile

For more information, see Addressing Blob Service

Requests.

Before you make your request to start the dataflow job,

make sure that the Blob Service URL is available publicly

or shared with a signature key. If the URL is shared with

a signature key, it must be encoded. For more

information, see Managing Access to Containers and

Parameter Alia

s

Description Values

or include

the data

to process

in the

HTTP

request. If

you do

both, the

URL

returns an

error.

Blobs.

The following content types are supported for data that is

retrieved from an HTTP server.

application/xml

text/xml

text/plain

application/octet-stream [for compressed data]

Example:

dataLocation=http://myServer.myDomain.com/spatialDat

aSource

input Required. The

format of the input

data file.


xml

csv

tab

pipe

For more information about input files for a Geocode

Dataflow, see Geocode Dataflow Data Schema - Version

2.0.

Example: input=csv

key Required. A Bing

Maps Key to use

for the geocode

job.

A Bing Maps Key obtained from the Bing Maps Account

Center.


output format for

the response.


json [default]

xml

Example: output=xml

Input

This URL supports the following input formats. For examples, see Geocode Dataflow Sample

Input and Output Data Version 2.0.

When you create the HTTP request to upload data and create a geocode job, you must post the

input data in the body of the request or set the dataLocation parameter to a URL where your data

can be retrieved. You must also set the content type in the request to one of the following values,

depending on the format of the input data.

XML (application/xml)

Comma-delimited values (text/plain)

Tab-delimited values (text/plain)

Pipe-delimited values (text/plain)

Binary (application/octet-stream) [Specify this format when you upload compressed data from

a Blob Service REST API location using the dataLocation parameter.]

Examples

This example creates a geocode job for spatial data that is provided in an xml format.

http://spatial.virtualearth.net/REST/v1/Dataflows/Geocode?input=xml&key=BingMapsKey

This example creates a geocode job for spatial data that is provided in an xml format and assigns

a description My dataflow to the job.

http://spatial.virtualearth.net/REST/v1/Dataflows/Geocode?input=xml&key=BingMapsKey

Response

The response to this URL contains a representation of the geocode dataflow job instance.

This URL supports the following response formats.

JSON (application/json)

XML (application/xml)

For information about the response, see Geocode Dataflow Response Description.

Sample Code

The following code shows how to create a job to geocode spatial data. The data you want to

geocode is uploaded as part of the job creation process. This code is part of a complete Geocode

Dataflow code sample. To view the complete code sample, see Geocode Dataflow Sample Code.

You may also want to read the Geocode Dataflow Walkthrough to get a step-by-step description

of how to use the Geocode Dataflow. The walkthrough includes example URLs and HTTP

responses.

//Creates a geocode dataflow job and uploads spatial data to process.

//Parameters:

// dataFilePath: The path to the file that contains the spatial data to

geocode.

// dataFormat: The format of the input data. Possible values are xml, csv, tab

and pipe.

// key: The Bing Maps Key to use for this job. The same key is used to get job

status and download results.

// description: Text that is used to describe the geocode dataflow job.

//Return value : A URL that defines the location of the geocode dataflow job that

was created.

static string CreateJob(string dataFilePath, string dataFormat, string key,

string description)

{

//Define parameters for the HTTP request

//

// The 'Content-Type' header of the HTTP Request must be "text/plain" or

"application/xml"

// depending on the input data format.

//

string contentType = "text/plain";

if (dataFormat.Equals("xml", StringComparison.OrdinalIgnoreCase))

contentType = "application/xml";

StringBuilder queryStringBuilder = new StringBuilder();

//

// The 'input'(input format) and 'key' (Bing Maps Key) parameters are

required.

//

queryStringBuilder.Append("input=").Append(Uri.EscapeUriString(dataFormat));

queryStringBuilder.Append("&");

queryStringBuilder.Append("key=").Append(Uri.EscapeUriString(key));

if (!String.IsNullOrEmpty(description))

{

//

// The 'description' parameter is optional.

//

queryStringBuilder.Append("&");

}

//Build the HTTP URI that will upload and create the geocode dataflow job

UriBuilder uriBuilder = new UriBuilder("http://spatial.virtualearth.net");

uriBuilder.Path = "/REST/v1/dataflows/geocode";

uriBuilder.Query = queryStringBuilder.ToString();

//Include the data to geocode in the HTTP request

using (FileStream dataStream = File.OpenRead(dataFilePath))

{

HttpWebRequest request =

(HttpWebRequest)WebRequest.Create(uriBuilder.Uri);

//

// The HTTP method must be 'POST'.

//

request.Method = "POST";

request.ContentType = contentType;

using (Stream requestStream = request.GetRequestStream())

{

byte[] buffer = new byte[16384];

int bytesRead = dataStream.Read(buffer, 0, buffer.Length);

while (bytesRead > 0)

{

requestStream.Write(buffer, 0, bytesRead);

bytesRead = dataStream.Read(buffer, 0, buffer.Length);

}

}

//Submit the HTTP request and check if the job was created successfully.

using (HttpWebResponse response = (HttpWebResponse)request.GetResponse())

{

//

// If the job was created successfully, the status code should be

// 201 (Created) and the 'Location' header should contain a URL

// that defines the location of the new dataflow job. You use this

// URL with the Bing Maps Key to query the status of your job.

//

if (response.StatusCode != HttpStatusCode.Created)

throw new Exception ("An HTTP error status code was encountered

when creating the geocode job.");

string dataflowJobLocation = response.GetResponseHeader("Location");

if (String.IsNullOrEmpty(dataflowJobLocation))

throw new Exception ("The 'Location' header is missing from the

HTTP response when creating a goecode job.");

return dataflowJobLocation;

}

}

}

HTTP Status Codes

For more details about these HTTP status codes, see Status Codes and Error Handling.

When the request is successful, the following HTTP status code is returned.

201

When the request is not successful, the response returns one of the following errors.

400

500

503

The response may contain a 503 HTTP status error code when the number of

pending geocode dataflow jobs is exceeded. The maximum number of pending

geocode dataflow jobs that can be associated with a Bing Maps Key is 10.

Get Status of a Geocode Job

Use the following URL to get the status of a geocode job.

Supported HTTP Methods

GET

URL template

This template supports both HTTP and HTTPS protocols. URLs in the response use

HTTPS protocol.

Get status information for a geocode job.

The Bing Maps Key that you specify must be the same Bing Maps Key that you used to create

the job. A URL in the following format without the Bing Maps Key is provided in the response to

the URL request that you made to Create a Geocode Job and Upload Data. The URL is specified

in a link field with an attribute of self. For more information, see Geocode Dataflow Response

Description.

http://spatial.virtualearth.net/REST/v1/Dataflows/Geocode/jobID?output=output&key=BingMap

sKey

Template Parameters

Parameter names and values are not case-sensitive except for the key parameter value.


jobID Required. The

ID of the job.

When you request a dataflow job, the job ID is

returned in the ID field of the response. For

more information, see Geocode Dataflow

Response Description.

Example:

e14b1d9bd65c4b9d99d267bbb8102ccf

key Required. The

Bing Maps Key

that you used to

create the

A Bing Maps Key from the Bing Maps Account

Center.

Example:

key=abc123def456ghi789abc123def456ghi789


geocode job.


output format for

the response.


json [default]

xml

Example: o=xml

Examples

This example requests resource information for the job with an ID of

e14b1d9bd65c4b9d99d267bbb8102ccf that was created by using the Bing Maps Key

b1c323ea234b1c323ea234b1c323ea234.

http://spatial.virtualearth.net/REST/v1/Dataflows/Geocode/e14b1d9bd65c4b9d99d267bbb8102cc

f?key=b1c323ea234b1c323ea234b1c323ea234

Response

This URL supports the following response formats.

JSON: application/json

XML: application/xml

For information about the response, see Geocode Dataflow Response Description.

Sample Code

The following code shows how to get the status of a geocode job. This code is part of a complete

Geocode Dataflow code sample. To view the complete code sample, see Geocode Dataflow

Sample Code. You may also want to read the Geocode Dataflow Walkthrough to get a step-by-

step description of how to use the Geocode Dataflow. The walkthrough includes example URLs

and HTTP responses.

class DownloadDetails

{

public string jobStatus { get; set; }

public string suceededlink { get; set; }

public string failedlink { get; set; }

}

//Checks the status of a dataflow job and defines the URLs to use to download results

when the job is completed.

//Parameters:

// dataflowJobLocation: The URL to use to check status for a job.

// key: The Bing Maps Key for this job. The same key is used to create the job and

download results.

//Return value: A DownloadDetails object that contains the status of the geocode dataflow

job (Completed, Pending, Aborted).

// When the status is set to Completed, DownloadDetails also contains the

links to download the results

static DownloadDetails CheckStatus(string dataflowJobLocation, string key)

{

DownloadDetails statusDetails = new DownloadDetails();

statusDetails.jobStatus = "Pending";

//Build the HTTP Request to get job status

UriBuilder uriBuilder = new UriBuilder(dataflowJobLocation + @"?key=" + key +

"&output=xml");

HttpWebRequest request = (HttpWebRequest)WebRequest.Create(uriBuilder.Uri);

request.Method = "GET";

//Submit the request and read the response to get job status and to retrieve the

links for

// downloading the job results

//Note: The following conditional statements make use of the fact that the 'Status'

field will

// always appear after the 'Link' fields in the HTTP response.

using (HttpWebResponse response = (HttpWebResponse)request.GetResponse())

{

if (response.StatusCode != HttpStatusCode.OK)

throw new Exception ("An HTTP error status code was encountered when checking

job status.");

using (Stream receiveStream = response.GetResponseStream())

{

XmlTextReader reader = new XmlTextReader(receiveStream);

while (reader.Read())

{

if (reader.IsStartElement())

{

if (reader.Name.Equals("Status"))

{

//return job status

statusDetails.jobStatus = reader.ReadString();

return (statusDetails);

}

else if (reader.Name.Equals("Link"))

{

//Set the URL location values for retrieving

// successful and failed job results

reader.MoveToFirstAttribute();

if (reader.Value.Equals("output"))

{

reader.MoveToNextAttribute();

if (reader.Value.Equals("succeeded"))

{

statusDetails.suceededlink = reader.ReadString();

}

else if (reader.Value.Equals("failed"))

{

statusDetails.failedlink = reader.ReadString();

}

}

}

}

}

}

}

return (statusDetails);

}

HTTP Status Codes

For more details about these HTTP status codes, see Status Codes and Error Handling.

When the request is successful, the following HTTP status code is returned.

200

When the request is not successful, the response returns one of the following HTTP status codes.

400

500

503

Download Geocode Job Results

The URLs to download results from a Geocode Job are provided when your job has completed

and you request job status. When your job has completed, the Status field in the job status

response is set to Completed and the URLs to use to download processed data are defined in the

response as XML Link values, or as part of a JSON links collection. You can distinguish these

link elements in the response because they have the attribute role set to output. These link

elements also specify the name attribute and set it to succeeded or failed to identify a download

URL for data that was processed successfully or for data that encountered errors during

processing. A link does not appear if there is no data to download. Therefore, if all your data was

processed successfully, a link with the name attribute and set it to failed will not appear in the

response. The following are examples of these link elements.

XML

https://spatial.virtualearth.net/REST/v1/dataflows/Geocode/5bf10c37df944

083b1879fbb0556e67e/output/succeeded

https://spatial.virtualearth.net/REST/v1/dataflows/Geocode/5bf10c37df944083

b1879fbb0556e67e/output/failed

JSON

"links":[

{

"name":"succeeded",

"role":"output",

"url":"https:\/\/spatial.virtualearth.net\/REST\/v1\/dataflows\/Geocode\/5bf10c3

7df944083b1879fbb0556e67e\/output\/succeeded"

},

{

"name":"failed",

"role":"output",

"url":"https:\/\/spatial.virtualearth.net\/REST\/v1\/dataflows\/Geocode\/5bf10c3

7df944083b1879fbb0556e67e\/output\/failed"

}

]

To use these URLs, you must add the Bing Maps Key parameter that you used to create the job.

For example, to download the data that was processed successfully in the above example, you

would add the parameter key MyDataflowJobKey where MyDataflowJobKey is the Bing Maps

Key that you used to create the job.

https://spatial.virtualearth.net/REST/v1/dataflows/Geocode/5bf10c37df944083b1879fbb0556e6

7e/output/succeeded?key=MyDataflowJobKey

For information about the Geocode Dataflow data schema, see Geocode Dataflow Data Schema

- Version 2.0.

Sample Code

The following code shows how to download the results of a geocode job. The geocoded results

are saved in text files. This code is part of a complete Geocode Dataflow code sample. To view

the complete code sample, see Geocode Dataflow Sample Code. You may also want to read the

Geocode Dataflow Walkthrough to get a step-by-step description of how to use the Geocode

Dataflow. The walkthrough includes example URLs and HTTP responses.

//Downloads job results to files names Success.txt (successfully geocoded results) and

// Failed.txt (info about spatial data that was not geocoded successfully).

//Parameters:

// statusDetails: Inclues job status and the URLs to use to download all geocoded

results.

// key: The Bing Maps Key for this job. The same key is used to create the job and get

job status.

static void DownloadResults(DownloadDetails statusDetails, string key)

{

//Write the results for data that was geocoded successfully to a file named

Success.xml

if (statusDetails.suceededlink != null &&

!statusDetails.suceededlink.Equals(String.Empty))

{

//Create a request to download successfully geocoded data. You must add the Bing

Maps Key to the

// download location URL provided in the response to the job status request.

UriBuilder successUriBuilder = new UriBuilder(statusDetails.suceededlink +

@"?key=" + key);

HttpWebRequest request1 =

(HttpWebRequest)WebRequest.Create(successUriBuilder.Uri);

request1.Method = "GET";

using (HttpWebResponse response = (HttpWebResponse)request1.GetResponse())

{


throw new Exception ("An HTTP error status code was encountered when

downloading results.");


{

StreamWriter successfile = new StreamWriter("Success.txt");

using (StreamReader r = new StreamReader(receiveStream))

{

string line;

while ((line = r.ReadLine()) != null)

{

successfile.Write(line);

}

}

successfile.Close();

}

}

}

//If some spatial data could not be geocoded, write the error information to a file

called Failed.xml

if (statusDetails.failedlink != null &&

!statusDetails.failedlink.Equals(String.Empty))

{

//Create an HTTP request to download error information. You must add the Bing

Maps Key to the

// download location URL provided in the response to the job status request.

UriBuilder failedUriBuilder = new UriBuilder(statusDetails.failedlink + @"?key="

+ key);

HttpWebRequest request2 =

(HttpWebRequest)WebRequest.Create(failedUriBuilder.Uri);

request2.Method = "GET";

using (HttpWebResponse response = (HttpWebResponse)request2.GetResponse())

{


throw new Exception ("An HTTP error status code was encountered when

downloading results.");


{

StreamWriter failedfile = new StreamWriter("Failed.txt");

using (StreamReader r = new StreamReader(receiveStream))

{

string line;

while ((line = r.ReadLine()) != null)

{

failedfile.Write(line);

}

}

failedfile.Close();

}

}

}

}

Geocode Dataflow Response Description

The following tables describe the response syntax for a Geocode Dataflow request in a set of

hierarchical tables. Examples in JSON and XML formats are also provided.

Response

The following fields are the top-level fields in the Geocode Dataflow response. Additional tables

describe the fields in each of the collections.

JSON XML Type Description

copyright Copyright string A copyright

notice.

brandLogoUri BrandLogoUri string A URL that

references a

brand image to

support

contractual

branding

requirements.


statusCode StatusCode integer The HTTP

Status code for

the request.

statusDescription StatusDescription string A description of

the HTTP

status code.

authenticationResultCode AuthenticationResultCode One of the following

values:

ValidCredentials

InvalidCredentials

CredentialsExpired

NotAuthorized

NoCredentials

None

A status code

that offers

additional

information

about

authentication

success or

failure.

traceId TraceId string A unique

identifier for the

request.

resourceSets ResourceSets collection A collection of

ResourceSet

objects. A

ResourceSet is

a container of

Resources

returned by the

request. For

more

information,

see the

ResourceSet

section below.

errorDetails ErrorDetails string[] A collection of

error

descriptions.

For example,

ErrorDetails

can identify

parameter


values that are

not valid or are

missing.

ResourceSet

The ResourceSet container provides the following information.


estimatedTotal EstimatedTotal long An estimate of the total

number of resources in

the ResourceSet.

resources Resources collection A collection of one or

more DataflowJob

resources. Information

about the DataflowJob

resource is found in

the DataflowJob

section.

DataflowJob

The DataflowJob resource container provides the following information.


id Id string A unique string that

identifies the dataflow

job. There are no

requirements for the

string format.

links Link URL A URL that is defined

by its role and name

attributes.

role:self: Use to

check the status of your

job.

role:output and

name:succeeded:


Use to download data

that was processed

successfully.

role:output and

name:failed: Use to

download data that was

not processed

successfully.

description Description string A user-defined

description of the

dataflow job. If a

description is not

specified when the

workflow is created, this

field is not included or

the value is null.

status Status One of the

following values:

Pending: The

dataflow job is

processing.

Completed: The

dataflow job has

completed. A

status of

completed does

not indicate

success.

Aborted: The

workflow

stopped

because of an

error.

The status of the

dataflow job.

createdDate CreatedDate DateTime The date and time that

the dataflow job was

created.

completedDate CompletedDate DateTime The date and time that

the dataflow job is


completed. If the Status

field is set to Pending,

the CompletedDate field

is not shown or is

empty.

totalEntityCount TotalEntityCount integer The total number of

entities that were

uploaded.

processedEntityCount ProcessedEntityCount integer The number of entities

that were processed.

This number included

entities that were

processed successfully

and those that failed. If

the field is set to 0, the

number of processed

entries is not known.

failedEntityCount FailedEntityCount integer The number of entities

that did not process

successfully because of

an error.

errorMessage ErrorMessage string Additional error

information that is

provided when the

Status is set to Aborted.

DataflowJob Response Examples

The following examples show DataflowJob resource content in JSON and XML formats.

JSON Example

{

"authenticationResultCode":"ValidCredentials",

"brandLogoUri":"http:\/\/spatial.virtualearth.net\/Branding\/logo_powered_by.png",

"copyright":" 2010 Microsoft and its suppliers. All rights reserved. This API cannot

be accessed and the content and any results may not be used, reproduced or transmitted in

any manner without express written permission from Microsoft Corporation.",

"resourceSets":[

{

"estimatedTotal":1,

"resources":[

{


"id":"5bf10c37df944083b1879fbb0556e67e",

"links":[

{

"role":"self",

"url":"https:\/\/spatial.virtualearth.net\/REST\/v1\/dataflows\/Geocode\/5bf10c37df944083

b1879fbb0556e67e"

},

{

"name":"succeeded",

"role":"output",

"url":"https:\/\/spatial.virtualearth.net\/REST\/v1\/dataflows\/Geocode\/5bf10c37df944083

b1879fbb0556e67e\/output\/succeeded"

},

{

"name":"failed",

"role":"output",

"url":"https:\/\/spatial.virtu

Documents

Bing Spatial Data Services