Share via

Geocode Dataflow Data Schema - Version 1.0

  • Article

Note

Bing Maps Spatial Data Service Geocode Dataflow API retirement

Bing Maps Spatial Data Service Geocode Dataflow API is deprecated and will be retired. Free (Basic) account customers can continue to use Bing Maps Spatial Data Service Geocode Dataflow API until June 30th, 2025. Enterprise account customers can continue to use Bing Maps Spatial Data Service Geocode Dataflow API until June 30th, 2028. To avoid service disruptions, all implementations using Bing Maps Spatial Data Service Geocode Dataflow API will need to be updated to use Azure Maps Get Geocoding Batch or Azure Maps Get Reverse Geocoding Batch API by the retirement date that applies to your Bing Maps for Enterprise account type. Azure Maps Geocoding Batch API and Azure Maps Reverse Geocode Batch API will be updated to support a larger number of locations per batch soon. For detailed migration guidance, see Migrate Bing Maps Geocode Dataflow API.

Azure Maps is Microsoft's next-generation maps and geospatial services for developers. Azure Maps has many of the same features as Bing Maps for Enterprise, and more. To get started with Azure Maps, create a free Azure subscription and an Azure Maps account. For more information about azure Maps, see Azure Maps Documentation. For migration guidance, see Bing Maps Migration Overview.

The Geocode Dataflow API supports the following formats for uploading and downloading spatial data:

  • Text files with values separated by comma, tab, or pipe (|) characters.
  • XML

Note

If you are a new user, use the latest version 2.0 of the data schema.

This topic describes the spatial data schema for version 1.0 the Geocode Dataflow API. Text file and the XML schema definitions are provided along with descriptions of the fields. For examples of input and output spatial data in all formats, see Sample Input and Output v1.0.

Text File Schema

The following text file schema shows how the input and output values for the Geocode Dataflow are organized in a text file. Note that there are GeocodeRequest, GeocodeResponse, and ReverseGeocodeRequest values. The Geocode Request fields define location information to geocode. The ReverseGeocodeRequest fields provide latitude and longitude information to reverse geocode. The GeocodeResponse fields are populated with the processed output data. Each item of data must provide information or a blank entry for each of these fields. Descriptions of the fields are provided in the Data Schema Definitions section below.

GeocodeEntity/@Id  
GeocodeEntity/GeocodeRequest/@Culture  
GeocodeEntity/GeocodeRequest/@Query  
GeocodeEntity/GeocodeRequest/Address/@AddressLine  
GeocodeEntity/GeocodeRequest/Address/@AdminDistrict  
GeocodeEntity/GeocodeRequest/Address/@CountryRegion  
GeocodeEntity/GeocodeRequest/Address/@District  
GeocodeEntity/GeocodeRequest/Address/@FormattedAddress  
GeocodeEntity/GeocodeRequest/Address/@Locality  
GeocodeEntity/GeocodeRequest/Address/@PostalCode  
GeocodeEntity/GeocodeRequest/Address/@PostalTown  
GeocodeEntity/GeocodeRequest/ConfidenceFilter/@MinimumConfidence  
GeocodeEntity/GeocodeResponse/Address/@AddressLine  
GeocodeEntity/GeocodeResponse/Address/@AdminDistrict  
GeocodeEntity/GeocodeResponse/Address/@CountryRegion  
GeocodeEntity/GeocodeResponse/Address/@District  
GeocodeEntity/GeocodeResponse/Address/@FormattedAddress  
GeocodeEntity/GeocodeResponse/Address/@Locality  
GeocodeEntity/GeocodeResponse/Address/@PostalCode  
GeocodeEntity/GeocodeResponse/Address/@PostalTown  
GeocodeEntity/GeocodeResponse/RooftopLocation/@Latitude  
GeocodeEntity/GeocodeResponse/RooftopLocation/@Longitude  
GeocodeEntity/GeocodeResponse/InterpolatedLocation/@Latitude  
GeocodeEntity/GeocodeResponse/InterpolatedLocation/@Longitude  
GeocodeEntity/GeocodeResponse/@Confidence  
GeocodeEntity/GeocodeResponse/@DisplayName  
GeocodeEntity/GeocodeResponse/@EntityType  
GeocodeEntity/GeocodeResponse/@StatusCode  
GeocodeEntity/GeocodeResponse/@FaultReason  
GeocodeEntity/ReverseGeocodeRequest/Location/@Latitude  
GeocodeEntity/ReverseGeocodeRequest/Location/@Longitude

The following two input values show an address to geocode and a latitude and longitude pair to reverse geocode. Note that both examples contain a value or blank space for each element in the text file schema.

1,en-US,,16630 Redmond Way,WA,,,,Redmond,98052,,,,,,,,,,,,,,,,,,,,,,,,  
2,en-gb,,,,,,,,,,,,,,,,,,,,,,,,,,,,53.77848387,-1.719561517

XML Schema

The following schema is the XML schema for spatial data. Descriptions of the fields are provided in the Data Schema Definitions section below.

<?xml version="1.0" encoding="utf-8"?>  
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http://schemas.microsoft.com/search/local/2010/5/geocode" xmlns:xs="http://www.w3.org/2001/XMLSchema">  
  <xs:element name="GeocodeFeed">  
    <xs:complexType>  
      <xs:sequence>  
        <xs:element maxOccurs="unbounded" name="GeocodeEntity">  
          <xs:complexType>  
            <xs:sequence>  
              <xs:element minOccurs="0" maxOccurs="1" name="ReverseGeocodeRequest">  
                <xs:complexType>  
                  <xs:sequence>  
                    <xs:element minOccurs="1" maxOccurs="1" name="Location">  
                      <xs:complexType>  
                        <xs:attribute name="Latitude" type="xs:decimal" use="required" />  
                        <xs:attribute name="Longitude" type="xs:decimal" use="required" />  
                      </xs:complexType>  
                    </xs:element>  
                    <xs:element minOccurs="0" maxOccurs="1" name="ConfidenceFilter">  
                      <xs:complexType>  
                        <xs:attribute name="MinimumConfidence" type="xs:string" use="required" />  
                      </xs:complexType>  
                    </xs:element>  
                  </xs:sequence>  
                  <xs:attribute name="Culture" type="xs:string" use="optional" />  
                  <xs:attribute name="IncludeEntityTypes" type="xs:string" use="optional" />  
                  <xs:attribute name="IncludeNeighborhood" type="xs:boolean" use="optional" />  
                  <xs:attribute name="MaxResults" type="xs:unsignedByte" use="optional" />  
                </xs:complexType>  
              </xs:element>  
              <xs:element minOccurs="0" maxOccurs="1" name="GeocodeRequest">  
                <xs:complexType>  
                  <xs:sequence minOccurs="0">  
                    <xs:element minOccurs="0" maxOccurs="1" name="Address">  
                      <xs:complexType>  
                        <xs:attribute name="AddressLine" type="xs:string" use="optional" />  
                        <xs:attribute name="AdminDistrict" type="xs:string" use="optional" />  
                        <xs:attribute name="Locality" type="xs:string" use="optional" />  
                        <xs:attribute name="PostalCode" type="xs:string" use="optional" />  
<xs:attribute name="CountryRegion" type="xs:string" use="optional" />  
</xs:complexType>  
                    </xs:element>  
                    <xs:element minOccurs="0" maxOccurs="1" name="ConfidenceFilter">  
                      <xs:complexType>  
                        <xs:attribute name="MinimumConfidence" type="xs:string" use="required" />  
                      </xs:complexType>  
                    </xs:element>  
                  </xs:sequence>  
                  <xs:attribute name="Culture" type="xs:string" use="optional" />  
                  <xs:attribute name="IncludeQueryParse" type="xs:boolean" use="optional" />  
                  <xs:attribute name="IncludeNeighborhood" type="xs:boolean" use="optional" />  
                  <xs:attribute name="MaxResults" type="xs:unsignedByte" use="optional" />  
                  <xs:attribute name="Query" type="xs:string" use="optional" />  
                </xs:complexType>  
              </xs:element>  
              <xs:element minOccurs="0" maxOccurs="unbounded" name="GeocodeResponse">  
                <xs:complexType>  
                  <xs:sequence>  
                    <xs:element minOccurs="0" maxOccurs="1" name="Address">  
                      <xs:complexType>  
                        <xs:attribute name="AddressLine" type="xs:string" use="optional" />  
                        <xs:attribute name="AdminDistrict" type="xs:string" use="optional" />  
                        <xs:attribute name="CountryRegion" type="xs:string" use="optional" />  
                        <xs:attribute name="District" type="xs:string" use="optional" />  
                        <xs:attribute name="FormattedAddress" type="xs:string" use="optional" />  
                        <xs:attribute name="Locality" type="xs:string" use="optional" />  
                        <xs:attribute name="PostalCode" type="xs:string" use="optional" />  
                        <xs:attribute name="PostalTown" type="xs:string" use="optional" />  
                        <xs:attribute name="Neighborhood" type="xs:string" use="optional" />  
                      </xs:complexType>  
                    </xs:element>  
                    <xs:element minOccurs="0" maxOccurs="1" name="RooftopLocation">  
                      <xs:complexType>  
                        <xs:attribute name="Latitude" type="xs:decimal" use="required" />  
                        <xs:attribute name="Longitude" type="xs:decimal" use="required" />  
                      </xs:complexType>  
                    </xs:element>  
                    <xs:element minOccurs="0" maxOccurs="1" name="InterpolatedLocation">  
                      <xs:complexType>  
                        <xs:attribute name="Latitude" type="xs:decimal" use="required" />  
                        <xs:attribute name="Longitude" type="xs:decimal" use="required" />  
                      </xs:complexType>  
                    </xs:element>  
                    <xs:element minOccurs="0" maxOccurs="unbounded" name="QueryParseValue">  
                      <xs:complexType>  
                        <xs:attribute name="Property" type="xs:string" use="required" />  
                        <xs:attribute name="Value" type="xs:string" use="required" />  
                      </xs:complexType>  
                    </xs:element>  
                  </xs:sequence>  
                  <xs:attribute name="DisplayName" type="xs:string" use="optional" />  
                  <xs:attribute name="EntityType" type="xs:string" use="optional" />  
                  <xs:attribute name="Confidence" type="xs:string" use="optional" />  
                  <xs:attribute name="StatusCode" type="xs:string" use="required" />  
                  <xs:attribute name="FaultReason" type="xs:string" use="optional" />  
                </xs:complexType>  
              </xs:element>  
              <xs:element minOccurs="0" maxOccurs="1" name="DataQuality">  
                <xs:complexType>  
                  <xs:attribute name="feedAlias" type="xs:string" use="required" />  
                </xs:complexType>  
              </xs:element>  
            </xs:sequence>  
            <xs:attribute name="Id" type="xs:string" use="required" />  
          </xs:complexType>  
        </xs:element>  
      </xs:sequence>  
    </xs:complexType>  
  </xs:element>  
</xs:schema>

The following two input values show a location to geocode and a latitude and longitude pair to reverse geocode.

<GeocodeFeed>  
  <GeocodeEntity Id="001" xmlns="http://schemas.microsoft.com/search/local/2010/5/geocode">  
    <GeocodeRequest Culture="en-US">  
      <Address AddressLine="16630 Redmond Way" AdminDistrict="WA" Locality="Redmond" PostalCode="98052" />  
    </GeocodeRequest>  
  </GeocodeEntity>  
  <GeocodeEntity Id="012" xmlns="http://schemas.microsoft.com/search/local/2010/5/geocode">  
    <ReverseGeocodeRequest Culture="en-gb">  
     <Location Longitude="-1.71956151723862" Latitude="53.7784838676453"/>  
    </ReverseGeocodeRequest>  
  </GeocodeEntity>  
</GeocodeFeed>

Data Schema Definitions

The following table provides descriptions of the fields in the spatial data schema. Field values are not case-sensitive.

Field Operation Values
Id Geocode Request A string that contains the ID of a spatial data input value.

Example: 1
Culture Geocode Request A string specifying the culture.

Example: en-us [default]
Query Geocode Request A query string that contains address information to geocode.

Example: 1600 Pennsylvania Ave NW Washington DC
MaxResults Geocode Request

Geocode Response		 An integer from 1 to 20 specifying the maximum number of results to return.
IncludeNeighborhood Geocode Request

Geocode Response		 A boolean value (true|false or1|0) that specifies whether to return neighborhood information in the address.

Example: Kiniski Gardens
IncludeQueryParse Geocode Request

Geocode Response		 A boolean value (true|false or1|0) that specifies whether to return parsing information.

This option is available with XML requests only.
QueryParseValue Geocode Response One or more property-value query-parse pairs.

Example: <QueryParseValue Property="Landmark" Value="Space Needle" />
IncludeEntityTypes Geocode Request

Geocode Response		 A list of POI Entity Types to return. This parameter is only available when you are reverse-geocoding, and only returns a geocoded address if the entity type for that address is one of the entity types you specified.

For a list of entity types, see Location and Area Types.
EntityType Geocode Response A string specifying the entity type of the location.

For a list of entity types, see Location and Area Types.

Examples:

Address

RoadBlock
Address.AddressLine Geocode Request

Geocode Response		 A string specifying the street line of an address. The AddressLine property is the most precise, official line for an address relative to the postal agency that services the area specified by the Locality, PostalTown, or PostalCode properties.

Example: 1 Microsoft Way
Address.AdminDistrict Geocode Request

Geocode Response		 A string specifying the subdivision name within the country or region for an address. This element is also commonly treated as the first order administrative subdivision; but in some cases, it is the second, third, or fourth order subdivision within a country, a dependency, or a region.

Example: WA
Address.CountryRegion Geocode Request

Geocode Response		 A string specifying the country or region name of an address.

Example: US
Address.District Geocode Request A string specifying the higher level administrative subdivision used in some countries or regions.
Address.FormattedAddress Geocode Response A string that contains a full formatted address

Note: Do not use this field as a geocode request value. This field is used in the response.
Address.Locality Geocode Request

Geocode Response		 A string specifying the populated place for the address. This commonly refers to a city, but may refer to a suburb or a neighborhood in certain countries/regions.

Example: Seattle
Address.Neighborhood Geocode Response A string specifying the neighborhood for the address.
Address.PostalCode Geocode Request

Geocode Response		 A string specifying the post code, postal code, or ZIP Code of an address.

Example: 98178
Address.PostalTown Geocode Request A string specifying the postal city of an address.
ConfidenceFilter.MinimumConfidence Geocode Request A string specifying the minimum confidence required for the result.

The following are possible confidence values:

- Low
- Medium
- High

Example: High
Location.Latitude

Location.Longitude		 Reverse Geocode Request A set of double values representing degrees of latitude and longitude.

Valid range of latitude values: [-90, +90]

Example: 47.673099

Valid range of longitude values: [-180, +180]

Example: -122.11871
RooftopLocation.Latitude

RooftopLocation.Longitude		 Geocode Response A pair of double values representing degrees of latitude and longitude that are associated with an address.
InterpolatedLocation.Latitude

InterpolatedLocation.Longitude		 Geocode Response A pair of double values representing degrees of latitude and longitude that are the result of interpolating between two points.
Confidence Geocode Response A string specifying the confidence of the result.

The following are possible confidence values:

- Low
- Medium
- High
DisplayName Geocode Response A string specifying the display name for the response.

Example: 16552 NE 74th St, Redmond, WA 98052-7804
StatusCode Geocode Response A string that provides information about the success of the operation.

Examples:

Success

BadRequest
FaultReason Geocode Response Information about an error that occurred during the geocode dataflow job. This value is provided only for data that was not processed successfully.

Example: The Address.FormattedAddress property must not be specified because it is an output-only property.