GetFileFormat

Purpose:

This request will return the SRC file format value given a description.  The description probably will come from GetFileFormatList above.  This is useful is you have populated a file open dialog and wish to go ahead and open the file, but don't know its file format value.

The request may use the file format description (ie "Comma-Delineated Text Files (*.csv)|*.csv") as a value attribute or a file name as a name attribute.  If using the name attribute, matching is done by extension and the first occurence of the match will be returned.  This is questionable for files with the .dbf extension, since file format '2' will always be returned.  Using the file format description is the least ambiguous match to use.

Request DTD:

<?xml version="1.0" encoding="UTF-8"?>
<!-- DTD for GetFileFormat Request -->
<!ELEMENT GetFileFormat (FilterText)>
<!ELEMENT FilterText EMPTY>
  <!ATTLIST FilterText value CDATA #IMPLIED>
  <!ATTLIST FilterText name CDATA #IMPLIED>

Request Schema:

<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <xsd:element name="GetFileFormat">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element ref="FilterText"/>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="FilterText">
    <xsd:complexType>
      <xsd:attribute name="value" default="" use="optional" type="xsd:string"/>
      <xsd:attribute name="name" default="" use="optional" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
</xsd:schema>

Code Example:

const char *pXmlResponse;
const char * pGetFileFormat = 
"<GetFileFormat>\n"
" <FilterText value=\"dBASE IV (*.dbf)\"/>\n"
"</GetFileFormat>\n";
printf("Test GetFileFormat\n%s\n", pGetFileFormat);
char defaultbuffer[256];
int defaulthandle = SC_Open("", defaultbuffer);
if (defaulthandle < 1)
{
	printf("Bad Handle: Could not open Solocast (handle = %d)\n", defaulthandle);
	exit(0);
}
pXmlResponse = SC_GetPropertiesString(defaulthandle, pGetFileFormat);
SC_Close(defaulthandle );

Request:

<GetFileFormat>
  <FilterText value="dBASE IV (*.dbf)"/>
</GetFileFormat>

Or using a file name:

<GetFileFormat>
  <FilterText name="my.dbf"/>
</GetFileFormat>

Response:

The response adds an index attribute set to the internal SRC file format index.

<GetFileFormat>
  <FilterText index="3" value="dBASE IV (*.dbf)"/>
</GetFileFormat>

Or the response using a name attribute:

<GetFileFormat>
  <FilterText desc="dBASE III (*.dbf)|*.dbf" name="myfile.dbf" flags="4" index="2"/>
</GetFileFormat>

File formats:

Argument	Description
String FilePath	The output file name
Enum FileFormat	Required if the outputting a database.  Ignored otherwise. Valid Values are (only specify the #): 0: Comma-Delineated Text Files (*.csv) 1: Microsoft Access 97 (*.mdb) 2: dBASE III (*.dbf) 3: dBASE IV (*.dbf) 4: dBASE 5 (*.dbf) (Not recomended, use 3 or 4) 5: Paradox 5.x (*.db) 6: FoxPro 2.6 (*.dbf) 9: HTML Export (*.htm) 10: MapInfo Interchange (*.mid/*.mif) 11: MapInfo Table (*.tab) 12: SHP File (*.shp)

GetTableList

Purpose:

Data source files which have not set the FILE_FLAG_NO_TABLES contain tables within the file name (typically as files within a folder named the filename).  For these data source files we need to also ask which table to open (the datawrap tablename parameter).  Excel workbooks, Paradox and Access databases typically require tables to be named.

The response returns a list of FileTable elements whose name attribute identifies the tables found within the database.  The name attribute values are suitable for populating a table select dialog.

Request DTD:

<?xml version="1.0" encoding="UTF-8"?>
<!-- DTD for GetTableList Request -->

<!ELEMENT GetTableList (File)>
<!ELEMENT File EMPTY>
  <!ATTLIST File path CDATA #REQUIRED>

Request Schema:

<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <xsd:element name="File">
    <xsd:complexType>
      <xsd:attribute name="path" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="GetTableList">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element ref="File"/>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
</xsd:schema>

Code Example:

const char *pXmlResponse;
const char * pGetTableList = 
"<GetTableList>\n"
" <File path=\"s:/solocast/xtreme.mdb\"/>\n"
"</GetTableList>\n";
printf("Test GetTableList\n%s\n", pGetTableList);
char defaultbuffer[256];
int defaulthandle = SC_Open("", defaultbuffer);
if (defaulthandle < 1)
{
	printf("Bad Handle: Could not open Solocast (handle = %d)\n", defaulthandle);
	exit(0);
}
pXmlResponse = SC_GetPropertiesString(defaulthandle, pGetTableList);
SC_Close(defaulthandle );

Request:

<GetTableList>
  <File path="s:/solocast/xtreme.mdb"/>
</GetTableList>

Response:

<GetTableList count=15>
  <File path="s:/solocast/xtreme.mdb"/>
  <FileTable name="Credit"/>
  <FileTable name="Customer"/>
  <FileTable name="Employee"/>
  <FileTable name="Employee Addresses"/>
  <FileTable name="Financials"/>
  <FileTable name="Orders"/>
  <FileTable name="Orders Detail"/>
  <FileTable name="Product"/>
  <FileTable name="Product Type"/>
  <FileTable name="Purchases"/>
  <FileTable name="Supplier"/>
  <FileTable name="Xtreme Info"/>
  <FileTable name="Credit_Limits"/>
  <FileTable name="List Totals"/>
  <FileTable name="Top Customers"/>
</GetTableList>

<GetTableList>
  <File path="s:/solocast/xtreme.mdb"/>
  <Error reason="s:/solocast/xtreme.mdb does not exist"/>
</GetTableList>

GetUnits

Purpose:

If the user needs to select from units, GetUnits returns the available unit selections and their types.

Code Example:

const char *pXmlResponse;
const char * pGetUnits = 
"<GetUnits>\n"
"</GetUnits>\n";
printf("Test GetUnits\n%s\n", pGetUnits);
char defaultbuffer[256];
int defaulthandle = SC_Open("", defaultbuffer);
if (defaulthandle < 1)
{
	printf("Bad Handle: Could not open Solocast (handle = %d)\n", defaulthandle);
	exit(0);
}
pXmlResponse = SC_GetPropertiesString(defaulthandle, pGetUnits);
SC_Close(defaulthandle );

Request:

 <GetUnits>
</GetUnits>

Response:

 <GetUnits>
  <Unit desc="Distance in Miles" type="Distance" value="Miles"/>
  <Unit desc="Distance in Kilometers" type="Distance" value="Kilometers"/>
  <Unit desc="Drivetime in Minutes" type="Drivetime" value="Minutes"/>
</GetUnits>

There is no abnormal response. 

GetGeographyTypes

Purpose:

The initial selection of geography types is used to begin populating a geography selection tree control, or other geography selection mechanism.  Calling the GetGeographyTypes returns the primary geography selections for the dataset used to open the Solocast handle.  The response contains a list of Selection elements.  Each Selection element contains a key attribute (used to pass to the Solocast dll for further expansion) and a desc attribute, used to display to the user for selection.

The initial selections will vary by Dataset.  Only the Geography Types for the current dataset (the one used to open Solocast), are returned.

Internally, the initial geography selections actually have no licensing associated with them.  It is not until the children of the these initial selection are selected, that licensing begins to appear.

Code Example:

const char *pXmlResponse;
const char * pGetPrimaryGeoDescriptions = 
"<GetGeographyTypes>\n"
"</GetGeographyTypes>\n";
printf("Test GetGeographyTypes\n%s\n", pGetPrimaryGeoDescriptions);
char defaultbuffer[256];
int defaulthandle = SC_Open("", defaultbuffer);
if (defaulthandle < 1)
{
	printf("Bad Handle: Could not open Solocast (handle = %d)\n", defaulthandle);
	exit(0);
}
pXmlResponse = SC_GetPropertiesString(defaulthandle, pGetPrimaryGeoDescriptions);
SC_Close(defaulthandle );

Request:

 <GetGeographyTypes>
</GetGeographyTypes>

Response:

<GetGeographyTypes count="13">
  <Selection key="BG" desc="Block Groups"/>
  <Selection key="County" desc="Counties"/>
  <Selection key="DMA" desc="DMAs - Designated Market Areas"/>
  <Selection key="DMABySt" desc="DMAs by State"/>
  <Selection key="FullUS" desc="Entire US"/>
  <Selection key="MSA" desc="MSAs - Metropolitan Statistical Areas"/>
  <Selection key="MSABySt" desc="MSAs by State"/>
  <Selection key="State" desc="States"/>
  <Selection key="TR" desc="Census Tracts"/>
  <Selection key="Zip" desc="Zip Codes (Jan 2001)"/>
  <Selection key="ZipByCn" desc="Zips by County (Jan 2001)"/>
  <Selection key="ZipByDMA" desc="Zips by DMA (Jan 2001)"/>
  <Selection key="ZipByMSA" desc="Zips by MSA (Jan 2001)"/>
</GetGeographyTypes>

There is no abnormal response. 

GetGeographySelection

Purpose:

Once the user begins expanding and contracting the geography selection control, the immediate children of the selection need be retrieved.  GetGeographySelection returns these children based upon the value contained in the QueryString element.

Request DTD:

<?xml version="1.0" encoding="UTF-8"?>
<!-- DTD for GetGeographySelections Request -->
<!ELEMENT GetGeographySelections (RootShortName, Key)>
<!ELEMENT RootShortName EMPTY>
  <!ATTLIST RootShortName value CDATA #REQUIRED>
<!ELEMENT Key EMPTY>
  <!ATTLIST Key value CDATA #REQUIRED>

Request Schema:

<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <xsd:element name="Key">
    <xsd:complexType>
      <xsd:attribute name="value" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="RootShortName">
    <xsd:complexType>
      <xsd:attribute name="value" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="GetGeographySelections">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element ref="RootShortName"/>
        <xsd:element ref="Key"/>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
</xsd:schema>

Code Example:

const char *pXmlResponse;
const char * pGetGeoSelections1 = 
"<GetGeographySelections>\n"
" <RootShortName value=\"BG\"/>\n"
" <Key value=\"\"/>\n"
"</GetGeographySelections>\n";
printf("Test GetGeographySelections\n%s\n", pGetGeoSelections1);
char defaultbuffer[256];
int defaulthandle = SC_Open("", defaultbuffer);
if (defaulthandle < 1)
{
	printf("Bad Handle: Could not open Solocast (handle = %d)\n", defaulthandle);
	exit(0);
}
pXmlResponse = SC_GetPropertiesString(defaulthandle, pGetGeoSelections1);
 const char * pGetGeoSelections2 = 
"<GetGeographySelections>\n"
" <RootShortName value=\"BG\"/>\n"
" <Key value=\"08\"/>\n"
"</GetGeographySelections>\n";
printf("Test GetGeographySelections\n%s\n", pGetGeoSelections2);
pXmlResponse = SC_GetPropertiesString(defaulthandle, pGetGeoSelections2);

SC_Close(defaulthandle );

Request:

<GetGeographySelections>
  <RootShortName value="BG"/>
  <Key value=""/>
</GetGeographySelections>

Response:

In the response below, the states between California and West Virginia have been omitted in the interest of space.

Of particular interest in the Profile element, is the licensedattribute, which depending on the licensing installed on the target machine, well return either True or False.  A licensedreturn of "True " means the profile is useable for reporting purposes, a return of "False" means running reports based upon this 'unlicensed' profile will cause a reporting error to occur.  We use the licensed attribute to determine which kind of image to display in the Profile selection tree.

<GetGeographySelections count="51">
<RootShortName value="BG"/>
<Key value=""/>
  <Selections leafNode="0" levelLongGeo="States" levelShortGeo="State">
    <Selection key="01" desc="Alabama" licensed="True" displayKey="01"/>
    <Selection key="02" desc="Alaska" licensed="True" displayKey="02"/>
    <Selection key="04" desc="Arizona" licensed="True" displayKey="04"/>
    <Selection key="05" desc="Arkansas" licensed="True" displayKey="05"/>
    <Selection key="06" desc="California" licensed="True" displayKey="06"/>
    ...
    <Selection key="54" desc="West Virginia" licensed="True" displayKey="54"/>
    <Selection key="55" desc="Wisconsin" licensed="True" displayKey="55"/>
    <Selection key="56" desc="Wyoming" licensed="True" displayKey="56"/>
  </Selections>
</GetGeographySelections>

Errors in Response:

Error Elements may be returned in the following cases:

1. The RootShortName element was not sent with the request.  The Error element's reason attribute will be set to "GetGeographySelections Validation failed: required information was not supplied."
2. The RootShortName value attribute identifies a shortname that could not be found in the current dataset's geographical inventory.  The Error elements reason attribute will be set to "GetGeographySelections Validation failed: Found No Children.".

GetCompareMethods

Purpose:

In order to select an Output Methodology, the GetCompareMethods call returns the key values (the values required by the Solocast workspace commands) and a user-friendly description used for the selection text.

Code Example:

const char *pXmlResponse;
const char * pCompareMethods = 
"<GetCompareMethods>\n"
"</GetCompareMethods>\n";
printf("Test GetCompareMethods\n%s\n", pCompareMethods);
char defaultbuffer[256];
int defaulthandle = SC_Open("", defaultbuffer);
if (defaulthandle < 1)
{
	printf("Bad Handle: Could not open Solocast (handle = %d)\n", defaulthandle);
	exit(0);
}
pXmlResponse = SC_GetPropertiesString(defaulthandle, pCompareMethods);
SC_Close(defaulthandle );

Request:

<GetCompareMethods>
</GetCompareMethods>

Response:

<GetCompareMethods count="9">
  <Method desc="Market Potential (Users)" name="Market Potential (Users)" fieldName="MPOT" sigDigits="0"/>
  <Method desc="Market Potential Index (Users)" name="Market Potential Index (Users)" fieldName="MPOTIDX" sigDigits="0"/>
  <Method desc="Market Potential (Volumetric)" name="Market Potential (Volumetric)" fieldName="MPOTVOL" sigDigits="0"/>
  <Method desc="Market Potential Index (Volumetric)" name="Market Potential Index (Volumetric)" fieldName="MPOTVOLIDX" sigDigits="0"/>
  <Method desc="Spearman Correlation (Users)" name="Spearman Correlation (Users)" fieldName="SPEAR" sigDigits="2"/>
  <Method desc="Pearson Correlation (Users)" name="Pearson Correlation (Users)" fieldName="PEARS" sigDigits="2"/>
  <Method desc="Spearman Correlation (Penetration)" name="Spearman Correlation (Penetration)" fieldName="SPEAR_PEN" sigDigits="2"/>
  <Method desc="Pearson Correlation (Penetration)" name="Pearson Correlation (Penetration)" fieldName="PEN" sigDigits="2"/>
  <Method desc="Penetration" name="Penetration" fieldName="Multiple" sigDigits="2"/>
</GetCompareMethods>

There is no abnormal response.

GeocodeAnAddress

Purpose:

Geocodes the address supplied in the request.  The response returned is either:

1.      The request document with error nodes added which identify the problem encountered.

2.      The Xml response returned by the geocoder wrapper.  This is supplied in case there are multiple matches that the user may be asked to choose from.

If the MatchesReturned element is not supplied, the best candidate is returned (MatchesReturned defaults to 1).

The response will include a MatchStatus attribute in the ReturnInfo element of the SrcGeocoderResponse.  This may have the values Exact, Multiple or None.  This status is based on the information you have supplied.  If you have supplied a complete address and the geocoder has been able to find it, you will get an exact match.

The response will contain either a USSPecific (US Specific) or a CASpecific (Canada specific) element.  If you are geocoding a US address, this element will have a GeoLevel attribute set either to Intersection, Street, Zip9, Zip7 or Zip5.  If you are geocoding a Canadian address this attribute will be set to either Intersection, Street, FSA or LDU.  The GeoLevel reflects the 'coarseness' of the data the request supplied.

Request DTD:

<?xml version="1.0" encoding="UTF-8"?>
<!-- DTD for GeocodeAnAddress Request -->
<!ELEMENT GeocodeAnAddress (MatchesReturned?, Address)>
<!ELEMENT MatchesReturned EMPTY>
  <!ATTLIST MatchesReturned value CDATA #REQUIRED>
<!ELEMENT Address (Street, Name, City, (State | Province), Code)>
<!ELEMENT Street (#PCDATA)>
<!ELEMENT Name (#PCDATA)>
<!ELEMENT City (#PCDATA)>
<!ELEMENT State (#PCDATA)>
<!ELEMENT Province (#PCDATA)>
<!ELEMENT Code (#PCDATA)>

Request Schema:

<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <xsd:element name="GeocodeAnAddress">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element ref="MatchesReturned" minOccurs="0" maxOccurs="1"/>
        <xsd:element ref="Address"/>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="Address">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element ref="Street"/>
        <xsd:element ref="Name"/>
        <xsd:element ref="City"/>
        <xsd:choice>
          <xsd:element ref="State"/>
          <xsd:element ref="Province"/>
        </xsd:choice>
        <xsd:element ref="Code"/>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="MatchesReturned">
    <xsd:complexType>
      <xsd:attribute name="value" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="Name" type="string"/>
  <xsd:element name="Street type="string/">
  <xsd:element name="City" type="string/>
  <xsd:element name="State" type="string"/>
  <xsd:element name="Province type="string"/>
  <xsd:element name="Code" type="string"/>
</xsd:schema>

Code Example:

const char *pXmlResponse;
const char * pGeocodeAddressTest = 
"<GeocodeAnAddress>\n"
" <Address>\n"
" <Street><![CDATA[300 Gold Run Road]]></Street>\n"
" <Name>Home</Name>\n"
" <City>Boulder</City>\n"
" <State>CO</State>\n"
" <Code>80302</Code>\n"
" </Address>\n"
"</GeocodeAnAddress>\n";
printf("Test GeocodeAnAddress\n%s\n", pGeocodeAddressTest);
char defaultbuffer[256];
int defaulthandle = SC_Open("", defaultbuffer);
if (defaulthandle < 1)
{
	printf("Bad Handle: Could not open Solocast (handle = %d)\n", defaulthandle);
	exit(0);
}
pXmlResponse = SC_GetPropertiesString(defaulthandle, pGeocodeAddressTest);
SC_Close(defaulthandle );

Request:

<GeocodeAnAddress>
  <Address>
    <Street>300 Gold Run Road</Street>
    <Name>Home</Name>
    <City>Boulder</City>
    <State>CO</State>
    <Code>80302</Code>
  </Address>
</GeocodeAnAddress>

Response:

The response is a standard response from the SRC Geocoder Wrapper, which see (Using Geocoder Wrapper with PinpointExplorer).

<SrcGeocoderResponse Version="1.0" VersionUsed="1.0" GeocoderUsed="PPExplorerUS">
  <ReturnInfo Id="0" MatchStatus="Exact" NumCandidatesFound="1">
    <Candidate Score="100.0">
      <CommonFields>
        <Lat>40.051685978</Lat>
        <Lon>-105.3746629</Lon>
        <FirstLine>300 GOLD RUN RD</FirstLine>
        <LastLine>BOULDER, CO 80302</LastLine>
        <City>BOULDER</City>
        <Province>CO</Province>
        <PostalCode>80302</PostalCode>
      </CommonFields>
      <USSpecific GeoLevel="Street">
        <HouseNumber>300</HouseNumber>
        <StreetPreDir></StreetPreDir>
        <StreetPreType></StreetPreType>
        <StreetName>GOLD RUN</StreetName>
        <StreetPostType>RD</StreetPostType>
        <StreetPostDir></StreetPostDir>
        <UnitDesignator></UnitDesignator>
        <UnitNumber></UnitNumber>
        <City>BOULDER</City>
        <StateAbbrev>CO</StateAbbrev>
        <Zip>80302</Zip>
        <Zip4></Zip4>
        <CensusId>080130137013007</CensusId>
        <ClusterLevelId>080130137013007</ClusterLevelId>
      </USSpecific>
    </Candidate>
  </ReturnInfo>
</SrcGeocoderResponse>

Canadian Example:

For Canadian geocoders, you may use either the State element or a Province element.  The Postal Code goes into the Code element's value attribute.

Request:

Either using the State element (for province) or substituting the Province element (in its place) works.  The two following sample requests are equivalent and produce the same output response.  

<GeocodeAnAddress>
  <Address>
    <Street>243 Consumers Road</Street>
    <Name>Office</Name>
    <City>Toronto</City>
    <State>ON</State>
    <Code>M2J 4WB</Code>
  </Address>
</GeocodeAnAddress>

<GeocodeAnAddress>
  <Address>
    <Street>243 Consumers Road</Street>
    <Name>Office</Name>
    <City>Toronto</City>
    <Province>ON</Province>
    <Code>M2J 4WB</Code>
  </Address>
</GeocodeAnAddress>

Response:

<?xml version = "1.0"?>
<SrcGeocoderResponse Version="1.0" VersionUsed="" GeocoderUsed="DMTICA">
  <ReturnInfo Id="1" MatchStatus="Exact" NumCandidatesFound="1">
    <Candidate Score="0.0">
      <CommonFields>
        <Lat>43.770523165</Lat>
        <Lon>-79.331158566</Lon>
        <FirstLine>243 CONSUMERS Road</FirstLine>
        <LastLine>Toronto, ON M2J 4WB</LastLine>
        <City>Toronto</City>
        <Province>ON</Province>
        <PostalCode>M2J 4WB</PostalCode>
      </CommonFields>
      <CASpecific GeoLevel="Street">
        <StreetAddress>243 CONSUMERS Road</StreetAddress>
        <City>Toronto</City>
        <ProvinceAbbrev>ON</ProvinceAbbrev>
        <ProvinceCode></ProvinceCode>
        <FSA>M2J</FSA>
        <LDU>4WB</LDU>
        <EA></EA>
        <ClusterLevelId></ClusterLevelId>
      </CASpecific>
    </Candidate>
  </ReturnInfo>
</SrcGeocoderResponse>

Multiple Match Example:

In cases in which there are multiple matches, the number of multiple matches will be returned.  If you do not wish to let the user select from the multiple matches, do not include the MatchesReturned element.  If you do include the MultipleMatches returned element, the value attribute tells the geocoder how many maximum matches to return.  You will get up to this many matches back, which you would then place into a 'Resolve Multiple Matches' dialog, and let the user select.

Request:

<GeocodeAnAddress>
  <MatchesReturned value="3"/>
  <Address>
    <Street>4383 Apple</Street>
    <Name>Multiple</Name>
    <City>Boulder</City>
    <State>CO</State>
    <Code>80301</Code>
  </Address>
</GeocodeAnAddress>

Response:

<SrcGeocoderResponse Version="1.0" VersionUsed="1.0" GeocoderUsed="PPExplorerUS">
  <ReturnInfo Id="0" MatchStatus="Multiple" NumCandidatesFound="2">
    <Candidate Score="96.8">
      <CommonFields>
        <Lat>40.054839731</Lat>
        <Lon>-105.25010144</Lon>
        <FirstLine>4383 APPLE CT</FirstLine>
        <LastLine>BOULDER, CO 80301</LastLine>
        <City>BOULDER</City>
        <Province>CO</Province>
        <PostalCode>80301</PostalCode>
      </CommonFields>
      <USSpecific GeoLevel="Street">
        <HouseNumber>4383</HouseNumber>
        <StreetPreDir></StreetPreDir>
        <StreetPreType></StreetPreType>
        <StreetName>APPLE</StreetName>
        <StreetPostType>CT</StreetPostType>
        <StreetPostDir></StreetPostDir>
        <UnitDesignator></UnitDesignator>
        <UnitNumber></UnitNumber>
        <City>BOULDER</City>
        <StateAbbrev>CO</StateAbbrev>
        <Zip>80301</Zip>
        <Zip4></Zip4>
        <CensusId>080130127013000</CensusId>
        <ClusterLevelId>080130127013000</ClusterLevelId>
      </USSpecific>
    </Candidate>
    <Candidate Score="96.8">
      <CommonFields>
        <Lat>40.054082301</Lat>
        <Lon>-105.25114448</Lon>
        <FirstLine>4383 APPLE WAY</FirstLine>
        <LastLine>BOULDER, CO 80301</LastLine>
        <City>BOULDER</City>
        <Province>CO</Province>
        <PostalCode>80301</PostalCode>
      </CommonFields>
      <USSpecific GeoLevel="Street">
        <HouseNumber>4383</HouseNumber>
        <StreetPreDir></StreetPreDir>
        <StreetPreType></StreetPreType>
        <StreetName>APPLE</StreetName>
        <StreetPostType>WAY</StreetPostType>
        <StreetPostDir></StreetPostDir>
        <UnitDesignator></UnitDesignator>
        <UnitNumber></UnitNumber>
        <City>BOULDER</City>
        <StateAbbrev>CO</StateAbbrev>
        <Zip>80301</Zip>
        <Zip4></Zip4>
        <CensusId>080130127013000</CensusId>
        <ClusterLevelId>080130127013000</ClusterLevelId>
      </USSpecific>
    </Candidate>
  </ReturnInfo>
</SrcGeocoderResponse>

Address Would NOT Geocode Example:

It is entirely possible that no matches will be returned.  In this case the returned NumCandidatesFound attribute will be set to zero.  You probably would want to warn to the user that the address given could not be geocoded.  In this example, we have given an address in Colorado but a zipcode from California.  There are no errors, the address simply would not geocode.

Request

<GeocodeAnAddress>
  <Address>
    <Street>300 Gold Run Road</Street>
    <Name>Home</Name>
    <City>Boulder</City>
    <State>CO</State>
    <Code>94025</Code>
  </Address>
</GeocodeAnAddress>

Response:

<SrcGeocoderResponse Version="1.0" VersionUsed="1.0" GeocoderUsed="PPExplorerUS">
  <ReturnInfo Id="0" MatchStatus="None" NumCandidatesFound="0"/>
</SrcGeocoderResponse>

Geocode Error:

There are cases when the GeocodeAnAddress request returns an Error element.

Request:

In the following request, not enough information is given to complete a geocode.

<GeocodeAnAddress>
  <Address>
    <Name>Home</Name>
  </Address>
</GeocodeAnAddress>

Response:

<SrcGeocoderResponse Version="1.0" VersionUsed="1.0" GeocoderUsed="PPExplorerUS">
  <ReturnInfo Id="0" MatchStatus="Error">
    <ErrorInfo ErrorCode="11">Invalid geocode request: FirstLine=, LastLine=, City=, Province=, PostalCode=</ErrorInfo>
  </ReturnInfo>
</SrcGeocoderResponse>

Errors in Response:

Error Elements may be returned in the following cases:

1. Required attributes could not be found.  They will be named.
2. The Profile path does not exist.
3. The Profile path attribute is empty.
4. A Profile name is not given.
5. We are processing a range of numbers, and the starting number is less than the ending number.

GetProfileSet_Select

Purpose:

GetProfileSet_Select formats and returns a ProfileSet_Select string for inclusion in a workspace.  The string returned may be in the ProfileSet_Select or ProfileSet_SelectAll format, depending on whether all the profiles within a profile set have been requested.  The response returns a Command element, which contains the command that would be added to the workspace command for generating reports or databases.

Request DTD:

<?xml version="1.0" encoding="UTF-8"?>
<!-- DTD for GetProfileSet_Select Request -->
<!ELEMENT GetProfileSet_Select (SelectionPage, Profile+)>
<!ELEMENT SelectionPage EMPTY>
  <!ATTLIST SelectionPage value (To|From) #REQUIRED>
<!ELEMENT Profile EMPTY>
  <!ATTLIST Profile path CDATA #REQUIRED>
  <!ATTLIST Profile name CDATA #REQUIRED>
  <!ATTLIST Profile number CDATA #IMPLIED>

Request Schema:

<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <xsd:element name="GetProfileSet_Select">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element ref="SelectionPage"/>
        <xsd:element ref="Profile" minOccurs="1" maxOccurs="unbounded"/>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="Profile">
    <xsd:complexType>
      <xsd:attribute name="path" use="required" type="xsd:string"/>
      <xsd:attribute name="number" default="" use="optional" type="xsd:string"/>
      <xsd:attribute name="name" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="SelectionPage">
    <xsd:complexType>
      <xsd:attribute name="value" use="required" type="SelectionPagevaluetype"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:simpleType name="SelectionPagevaluetype">
    <xsd:restriction base="xsd:string">
      <xsd:enumeration value="To"/>
      <xsd:enumeration value="From"/>
    </xsd:restriction>
  </xsd:simpleType>
</xsd:schema>

Code Example:

const char *pXmlResponse;
const char * pCheckGetProfileSet_Select_To = 
"<GetProfileSet_Select>\n"
" <SelectionPage value=\"To\"/>\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Ate Fast Food 14+ Times In Last 30 Days\" number=\"\" />\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Bought Bic Pens\" number=\"\" />\n"
" <Profile path=\"S:/solocast/MRI Attitudes.SCD\" name=\"Middle of the Road\" number=\"\" />\n"
" <Profile path=\"S:/solocast/MRI Attitudes.SCD\" name=\"Member of a Civic Club\" number=\"\" />\n"
"</GetProfileSet_Select>\n";
printf("Test GetProfileSet_Select\n%s\n", pCheckGetProfileSet_Select_To);
char defaultbuffer[256];
int defaulthandle = SC_Open("", defaultbuffer);
if (defaulthandle < 1)
{
	printf("Bad Handle: Could not open Solocast (handle = %d)\n", defaulthandle);
	exit(0);
}
pXmlResponse = SC_GetPropertiesString(defaulthandle, pCheckGetProfileSet_Select_To);

const char * pCheckGetProfileSet_SelectAll_To = 
"<GetProfileSet_Select>\n"
" <SelectionPage value=\"To\"/>\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Ate Fast Food 14+ Times In Last 30 Days\" number=\"\" />\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Bought Bic Pens\"/>\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Bought Colored Pencils Last Year\"/>\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Bought Crayons Last Year\"/>\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Bought Cross Pens\"/>\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Bought PaperMate Pens\"/>\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Eat at Family Restaurant and Steak Houses\"/>\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Eat at Fast Food Restaurant\"/>\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Expenditures Games &amp; Toys $200+ Last Year\"/>\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Ordered Take Out/Take Home Food in Last Month\"/>\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Own a Mont Blanc/Waterman Pen/Mech Pencil\"/>\n"
"</GetProfileSet_Select>\n";
printf("Test GetProfileSet_Select\n%s\n", pCheckGetProfileSet_SelectAll_To);
pXmlResponse = SC_GetPropertiesString(defaulthandle, pCheckGetProfileSet_SelectAll_To);

const char * pCheckGetProfileSet_Select_From = 
"<GetProfileSet_Select>\n"
" <SelectionPage value=\"From\"/>\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Ate Fast Food 14+ Times In Last 30 Days\" number=\"\" />\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Bought Bic Pens\" number=\"\" />\n"
" <Profile path=\"S:/solocast/MRI Attitudes.SCD\" name=\"Middle of the Road\" number=\"\" />\n"
" <Profile path=\"S:/solocast/MRI Attitudes.SCD\" name=\"Member of a Civic Club\" number=\"\" />\n"
"</GetProfileSet_Select>\n";
printf("Test GetProfileSet_Select\n%s\n", pCheckGetProfileSet_Select_From);
pXmlResponse = SC_GetPropertiesString(defaulthandle, pCheckGetProfileSet_SelectAll_To);

const char * pCheckGetProfileSet_SelectAll_From = 
"<GetProfileSet_Select>\n"
" <SelectionPage value=\"From\"/>\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Ate Fast Food 14+ Times In Last 30 Days\" number=\"\" />\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Bought Bic Pens\"/>\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Bought Colored Pencils Last Year\"/>\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Bought Crayons Last Year\"/>\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Bought Cross Pens\"/>\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Bought PaperMate Pens\"/>\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Eat at Family Restaurant and Steak Houses\"/>\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Eat at Fast Food Restaurant\"/>\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Expenditures Games &amp; Fromys $200+ Last Year\"/>\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Ordered Take Out/Take Home Food in Last Month\"/>\n"
" <Profile path=\"S:/solocast/Sample.SCD\" name=\"Own a Mont Blanc/Waterman Pen/Mech Pencil\"/>\n"
"</GetProfileSet_Select>\n";
printf("Test GetProfileSet_Select\n%s\n", pCheckGetProfileSet_SelectAll_From);
pXmlResponse = SC_GetPropertiesString(defaulthandle, pCheckGetProfileSet_SelectAll_From);
SC_Close(defaulthandle );

Request:

This request selects some of the profiles contained in the supplied Profile Set, so the Command returned is formatted using the ProfileSet_Select command.

<GetProfileSet_Select>
  <SelectionPage value="To"/>
  <Profile path="S:/solocast/Sample.SCD" name="Ate Fast Food 14+ Times In Last 30 Days" number="" />
  <Profile path="S:/solocast/Sample.SCD" name="Bought Bic Pens" number="" />
  <Profile path="S:/solocast/MRI Attitudes.SCD" name="Middle of the Road" number="" />
  <Profile path="S:/solocast/MRI Attitudes.SCD" name="Member of a Civic Club" number="" />
</GetProfileSet_Select>

This request selects all of the profiles contained in the supplied Profile Set, so the Command returned is formatted using the ProfileSet_SelectAll command.

<GetProfileSet_Select>
  <SelectionPage value="To"/>
  <Profile path="S:/solocast/Sample.SCD" name="Ate Fast Food 14+ Times In Last 30 Days" number="" />
  <Profile path="S:/solocast/Sample.SCD" name="Bought Bic Pens"/>
  <Profile path="S:/solocast/Sample.SCD" name="Bought Colored Pencils Last Year"/>
  <Profile path="S:/solocast/Sample.SCD" name="Bought Crayons Last Year"/>
  <Profile path="S:/solocast/Sample.SCD" name="Bought Cross Pens"/>
  <Profile path="S:/solocast/Sample.SCD" name="Bought PaperMate Pens"/>
  <Profile path="S:/solocast/Sample.SCD" name="Eat at Family Restaurant and Steak Houses"/>
  <Profile path="S:/solocast/Sample.SCD" name="Eat at Fast Food Restaurant"/>
  <Profile path="S:/solocast/Sample.SCD" name="Expenditures Games &amp; Toys $200+ Last Year"/>
  <Profile path="S:/solocast/Sample.SCD" name="Ordered Take Out/Take Home Food in Last Month"/>
  <Profile path="S:/solocast/Sample.SCD" name="Own a Mont Blanc/Waterman Pen/Mech Pencil"/>
</GetProfileSet_Select>

Response:

<GetProfileSet_Select>
  <SelectionPage value="To"/>
  <Profile name="Ate Fast Food 14+ Times In Last 30 Days" path="S:/solocast/Sample.SCD" number=""/>
  <Profile name="Bought Bic Pens" path="S:/solocast/Sample.SCD" number=""/>
  <Profile name="Middle of the Road" path="S:/solocast/MRI Attitudes.SCD" number=""/>
  <Profile name="Member of a Civic Club" path="S:/solocast/MRI Attitudes.SCD" number=""/>
  <Command value="ProfileSet_Select(S:/solocast/Sample.SCD,To,Ate Fast Food 14+ Times In Last 30 Days,Bought Bic Pens)"/>
</GetProfileSet_Select>

<GetProfileSet_Select>
  <SelectionPage value="To"/>
  <Profile name="Ate Fast Food 14+ Times In Last 30 Days" path="S:/solocast/Sample.SCD" number=""/>
  <Profile name="Bought Bic Pens" path="S:/solocast/Sample.SCD"/>
  <Profile name="Bought Colored Pencils Last Year" path="S:/solocast/Sample.SCD"/>
  <Profile name="Bought Crayons Last Year" path="S:/solocast/Sample.SCD"/>
  <Profile name="Bought Cross Pens" path="S:/solocast/Sample.SCD"/>
  <Profile name="Bought PaperMate Pens" path="S:/solocast/Sample.SCD"/>
  <Profile name="Eat at Family Restaurant and Steak Houses" path="S:/solocast/Sample.SCD"/>
  <Profile name="Eat at Fast Food Restaurant" path="S:/solocast/Sample.SCD"/>
  <Profile name="Expenditures Games &amp; Toys $200+ Last Year" path="S:/solocast/Sample.SCD"/>
  <Profile name="Ordered Take Out/Take Home Food in Last Month" path="S:/solocast/Sample.SCD"/>
  <Profile name="Own a Mont Blanc/Waterman Pen/Mech Pencil" path="S:/solocast/Sample.SCD"/>
  <Command value="ProfileSet_SelectAll(S:/solocast/Sample.SCD,To)"/>
</GetProfileSet_Select>

Errors in Response:

Error Elements may be returned in the following cases:

1. Required attributes could not be found.  They will be named.
2. The Profile path does not exist.
3. The Profile path attribute is empty.
4. A Profile name is not given.
5. We are processing a range of numbers, and the starting number is less than the ending number

ValidateNewDbProfile

Purpose:

This encapsulates validating a new database profile using the current new profile api.  Given the information required to build a Profile Set based upon Database information, the response returns the Commands that may be included in the Solocast workspace command that actually builds the Profile Set.

This request simply validates and formats Command strings that may be submitted to the Solocast engine using the appropriate CreateNewProfile API.

Request DTD:

<?xml version="1.0" encoding="UTF-8"?>
<!-- DTD for ValidateNewDbProfile Request -->
<!ELEMENT ValidateNewDbProfile (Type,Name,Input,Fields,OutputCodedFile?,OutputScdFile,(Base|ProfileBase)?)>
<!ELEMENT Type EMPTY>
  <!ATTLIST Type value (CensusCluster|Demographic) #REQUIRED>
<!ELEMENT Name EMPTY>
  <!ATTLIST Name value CDATA #REQUIRED>
<!ELEMENT Input EMPTY>
  <!ATTLIST Input path CDATA #REQUIRED>
  <!ATTLIST Input format CDATA #REQUIRED>
  <!ATTLIST Input tableName CDATA #IMPLIED>
<!ELEMENT Fields (Field+)>
<!ELEMENT Field EMPTY>
  <!ATTLIST Field type (address|city|lastline|state|province|zip|postalcode|census) #REQUIRED>
  <!ATTLIST Field name CDATA #REQUIRED>
  <!ATTLIST Field fieldNumber CDATA #IMPLIED>
<!ELEMENT OutputCodedFile EMPTY>
  <!ATTLIST OutputCodedFile path CDATA #REQUIRED>
  <!ATTLIST OutputCodedFile format CDATA #REQUIRED>
<!ELEMENT OutputScdFile EMPTY>
  <!ATTLIST OutputScdFile path CDATA #REQUIRED>
  <!ATTLIST OutputScdFile append CDATA #IMPLIED>
<!ELEMENT Base EMPTY>
  <!ATTLIST Base value (None|Automatic) #REQUIRED>
<!ELEMENT ProfileBase EMPTY>
  <!ATTLIST ProfileBase path CDATA #REQUIRED>
  <!ATTLIST ProfileBase name CDATA #REQUIRED>

Request Schema:

<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <xsd:element name="Name">
    <xsd:complexType>
      <xsd:attribute name="value" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="Type">
    <xsd:complexType>
      <xsd:attribute name="value" use="required" type="Typevaluetype"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="OutputScdFile">
    <xsd:complexType>
      <xsd:attribute name="path" use="required" type="xsd:string"/>
      <xsd:attribute name="append" default="" use="optional" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="Field">
    <xsd:complexType>
      <xsd:attribute name="fieldNumber" default="" use="optional" type="xsd:string"/>
      <xsd:attribute name="type" use="required" type="Fieldtypetype"/>
      <xsd:attribute name="name" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="OutputCodedFile">
    <xsd:complexType>
      <xsd:attribute name="format" use="required" type="xsd:string"/>
      <xsd:attribute name="path" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="Input">
    <xsd:complexType>
      <xsd:attribute name="tableName" default="" use="optional" type="xsd:string"/>
      <xsd:attribute name="format" use="required" type="xsd:string"/>
      <xsd:attribute name="path" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="Fields">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element ref="Field" minOccurs="1" maxOccurs="unbounded"/>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="ProfileBase">
    <xsd:complexType>
      <xsd:attribute name="path" use="required" type="xsd:string"/>
      <xsd:attribute name="name" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="ValidateNewDbProfile">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element ref="Type"/>
        <xsd:element ref="Name"/>
        <xsd:element ref="Input"/>
        <xsd:element ref="Fields"/>
        <xsd:element ref="OutputCodedFile" minOccurs="0" maxOccurs="1"/>
        <xsd:element ref="OutputScdFile"/>
        <xsd:choice>
          <xsd:element ref="Base"/>
          <xsd:element ref="ProfileBase"/>
        </xsd:choice>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="Base">
    <xsd:complexType>
      <xsd:attribute name="value" use="required" type="Basevaluetype"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:simpleType name="Basevaluetype">
    <xsd:restriction base="xsd:string">
      <xsd:enumeration value="None"/>
      <xsd:enumeration value="Automatic"/>
    </xsd:restriction>
  </xsd:simpleType>
  <xsd:simpleType name="Fieldtypetype">
    <xsd:restriction base="xsd:string">
      <xsd:enumeration value="address"/>
      <xsd:enumeration value="city"/>
      <xsd:enumeration value="lastline"/>
      <xsd:enumeration value="state"/>
      <xsd:enumeration value="province"/>
      <xsd:enumeration value="zip"/>
      <xsd:enumeration value="postalcode"/>
      <xsd:enumeration value="census"/>
    </xsd:restriction>
  </xsd:simpleType>
  <xsd:simpleType name="Typevaluetype">
    <xsd:restriction base="xsd:string">
      <xsd:enumeration value="CensusCluster"/>
      <xsd:enumeration value="Demographic"/>
    </xsd:restriction>
  </xsd:simpleType>
</xsd:schema>

Code Example:

const char *pXmlResponse;
const char * pCheckDBReturnsValidation = 
"<ValidateNewDbProfile>\n"
" <Type value=\"CensusCluster\"/>\n"
" <Name value=\"Custom Database Profile Set\"/>\n"
" <Input path=\"S:/solocast/BGTest.csv\" format=\"0\" tableName=\"\"/>\n"
" <Fields>\n"
"   <Field type=\"census\" name=\"BG\" fieldNumber=\"\"/>\n"
" </Fields>\n"
" <OutputScdFile path=\"s:/solocast/Custom Database Profile Set.scd\"/>\n"
"</ValidateNewDbProfile>\n";
printf("Test ValidateNewDbProfile\n%s\n", pCheckDBReturnsValidation);
char defaultbuffer[256];
int defaulthandle = SC_Open("", defaultbuffer);
if (defaulthandle < 1)
{
	printf("Bad Handle: Could not open Solocast (handle = %d)\n", defaulthandle);
	exit(0);
}
pXmlResponse = SC_GetPropertiesString(defaulthandle, pCheckDBReturnsValidation);

const char * pCheckDBReturnsProfiles = 
"<GetProfilesWithinProfileSet>\n"
" <Filter type=\"UserDb|Geo|Product|Polygon|Radial\"/>\n"
" <ProfileSet path=\"s:/solocast/Custom Database Profile Set.scd\"/>\n"
"</GetProfilesWithinProfileSet>\n";
printf("Test GetProfilesWithinProfileSet\n%s\n", pCheckDBReturnsProfiles);
pXmlResponse = SC_GetPropertiesString(defaulthandle, pCheckDBReturnsProfiles);

SC_Close(defaulthandle );

Request:

<ValidateNewDbProfile>
  <Type value="CensusCluster"/>
  <Name value="Custom Database Profile Set"/>
  <Input path="S:/solocast/BGTest.csv" format="0" tableName=""/>
  <Fields>
    <Field type="census" name="BG" fieldNumber=""/>
  </Fields>
  <OutputScdFile path="s:/solocast/Custom Database Profile Set.scd"/>
</ValidateNewDbProfile>

Response:

<ValidateNewDbProfile>
  <Type value="CensusCluster"/>
  <Name value="Custom Database Profile Set"/>
  <Input path="S:/solocast/BGTest.csv" format="0" tableName=""/>
  <Fields>
    <Field name="BG" type="census" fieldNumber=""/>
  </Fields>
  <OutputScdFile path="s:/solocast/Custom Database Profile Set.scd"/>
  <Commands count="5">
    <Commands value="In_Demographic_Input(&quot;S:/solocast/BGTest.csv&quot;, &quot;0&quot;)"/>
    <Commands value="In_Demographic_CensusClusterFI(&quot;BG&quot;)"/>
    <Commands value="Output_FilePath(&quot;s:/solocast/Custom Database Profile Set.scd&quot;)"/>
    <Commands value="In_Demographic_Name(&quot;Custom Database Profile Set&quot;)"/>
    <Commands value="Base(&quot;None&quot;)"/>
  </Commands>
</ValidateNewDbProfile>

Errors in Response:

Error Elements may be returned in the following cases:

1. Required attributes could not be found.  They will be named.
2. The information provided was not sufficient to validate the commands.
3. The Type element value is not either "CensusCluster" or "Demographic".

ValidateRingProfileFromFile

Purpose:

This encapsulates validating a new ring profile using the current new profile api, from an input file.    Given the information required to build a Profile Set based upon radius information, the response returns the Commands that may be included in the Solocast workspace command that actually builds the Profile Set.

This request simply validates and formats Command strings that may be submitted to the Solocast engine using the appropriate CreateNewProfile API.

Request DTD:

<?xml version="1.0" encoding="UTF-8"?>
<!-- DTD for ValidateRingProfileFromFile Request -->
<!ELEMENT ValidateRingProfileFromFile (Type,Input,RootName,Radius,Units,Fields,OutputScdFile,(Base|ProfileBase)?)>
<!ELEMENT Type EMPTY>
  <!ATTLIST Type value (SingleAddress|Address|LatLon) #REQUIRED>
<!ELEMENT Input EMPTY>
  <!ATTLIST Input path CDATA #REQUIRED>
  <!ATTLIST Input format CDATA #REQUIRED>
<!ELEMENT Radius EMPTY>
  <!ATTLIST Radius value CDATA #REQUIRED>
<!ELEMENT Units EMPTY>
  <!ATTLIST Units value (Miles|Kilometers|Minutes) #REQUIRED>
<!ELEMENT RootName EMPTY>
  <!ATTLIST RootName value CDATA #REQUIRED>
<!ELEMENT Fields (Field+)>
<!ELEMENT Field EMPTY>
  <!ATTLIST Field type (address|city|lastline|state|province|zip|postalcode|name|Lat|Lon) #REQUIRED>
  <!ATTLIST Field name CDATA #REQUIRED>
  <!ATTLIST Field fieldNumber CDATA #IMPLIED>
<!ELEMENT OutputScdFile EMPTY>
  <!ATTLIST OutputScdFile path CDATA #REQUIRED>
  <!ATTLIST OutputScdFile append CDATA #IMPLIED>
<!ELEMENT Base EMPTY>
  <!ATTLIST Base value (None|Automatic) #REQUIRED>
<!ELEMENT ProfileBase EMPTY>
  <!ATTLIST ProfileBase path CDATA #REQUIRED>
  <!ATTLIST ProfileBase name CDATA #REQUIRED>

Request Schema:

<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <xsd:element name="RootName">
    <xsd:complexType>
      <xsd:attribute name="value" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="Units">
    <xsd:complexType>
      <xsd:attribute name="value" use="required" type="Unitsvaluetype"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="Type">
    <xsd:complexType>
      <xsd:attribute name="value" use="required" type="Typevaluetype"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="OutputScdFile">
    <xsd:complexType>
      <xsd:attribute name="path" use="required" type="xsd:string"/>
      <xsd:attribute name="append" default="" use="optional" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="Field">
    <xsd:complexType>
      <xsd:attribute name="fieldNumber" default="" use="optional" type="xsd:string"/>
      <xsd:attribute name="type" use="required" type="Fieldtypetype"/>
      <xsd:attribute name="name" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="Input">
    <xsd:complexType>
      <xsd:attribute name="format" use="required" type="xsd:string"/>
      <xsd:attribute name="path" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="Fields">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element ref="Field" minOccurs="1" maxOccurs="unbounded"/>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="ValidateRingProfileFromFile">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element ref="Type"/>
        <xsd:element ref="Input"/>
        <xsd:element ref="RootName"/>
        <xsd:element ref="Radius"/>
        <xsd:element ref="Units"/>
        <xsd:element ref="Fields"/>
        <xsd:element ref="OutputScdFile"/>
        <xsd:choice>
          <xsd:element ref="Base"/>
          <xsd:element ref="ProfileBase"/>
        </xsd:choice>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="ProfileBase">
    <xsd:complexType>
      <xsd:attribute name="path" use="required" type="xsd:string"/>
      <xsd:attribute name="name" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="Radius">
    <xsd:complexType>
      <xsd:attribute name="value" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="Base">
    <xsd:complexType>
      <xsd:attribute name="value" use="required" type="Basevaluetype"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:simpleType name="Basevaluetype">
    <xsd:restriction base="xsd:string">
      <xsd:enumeration value="None"/>
      <xsd:enumeration value="Automatic"/>
    </xsd:restriction>
  </xsd:simpleType>
  <xsd:simpleType name="Fieldtypetype">
    <xsd:restriction base="xsd:string">
      <xsd:enumeration value="address"/>
      <xsd:enumeration value="city"/>
      <xsd:enumeration value="lastline"/>
      <xsd:enumeration value="state"/>
      <xsd:enumeration value="province"/>
      <xsd:enumeration value="zip"/>
      <xsd:enumeration value="postalcode"/>
      <xsd:enumeration value="name"/>
      <xsd:enumeration value="Lat"/>
      <xsd:enumeration value="Lon"/>
    </xsd:restriction>
  </xsd:simpleType>
  <xsd:simpleType name="Typevaluetype">
    <xsd:restriction base="xsd:string">
      <xsd:enumeration value="SingleAddress"/>
      <xsd:enumeration value="Address"/>
      <xsd:enumeration value="LatLon"/>
    </xsd:restriction>
  </xsd:simpleType>
  <xsd:simpleType name="Unitsvaluetype">
    <xsd:restriction base="xsd:string">
      <xsd:enumeration value="Miles"/>
      <xsd:enumeration value="Kilometers"/>
      <xsd:enumeration value="Minutes"/>
    </xsd:restriction>
  </xsd:simpleType>
</xsd:schema>

Code Example:

const char *pXmlResponse;
const char * pCreatePointFileEx = 
"<ValidateRingProfileFromFile>\n"
" <Type value=\"SingleAddress\"/>\n"
" <Input path=\"s:/solocast/BgTest.csv\" format=\"0\"/>\n"
" <RootName value=\"Custom Radius Profile Set\"/>\n"
" <Radius value=\"5\"/>\n"
" <Units value=\"Miles\"/>\n"
" <Fields>\n"
"   <Field type=\"name\" name=\"name\" fieldNumber=\"\"/>\n"
"   <Field type=\"address\" name=\"address\" fieldNumber=\"\"/>\n"
"   <Field type=\"city\" name=\"LAST_LINE\" fieldNumber=\"\"/>\n"
" </Fields>\n"
" <OutputScdFile path=\"s:/solocast/Custom Radius Profile Set.scd\"/>\n"
"</ValidateRingProfileFromFile>\n";
printf("Test ValidateRingProfileFromFile\n%s\n", pCreatePointFileEx);
char defaultbuffer[256];
int defaulthandle = SC_Open("", defaultbuffer);
if (defaulthandle < 1)
{
	printf("Bad Handle: Could not open Solocast (handle = %d)\n", defaulthandle);
	exit(0);
}
pXmlResponse = SC_GetPropertiesString(defaulthandle, pCreatePointFileEx);
SC_Close(defaulthandle );

Request:

<ValidateRingProfileFromFile>
  <Type value="SingleAddress"/>
  <Input path="s:/solocast/BgTest.csv" format="0"/>
  <RootName value="Custom Radius Profile Set"/>
  <Radius value="5"/>
  <Units value="Miles"/>
  <Fields>
    <Field type="name" name="name" fieldNumber=""/>
    <Field type="address" name="address" fieldNumber=""/>
    <Field type="city" name="LAST_LINE" fieldNumber=""/>
  </Fields>
  <OutputScdFile path="s:/solocast/Custom Radius Profile Set.scd"/>
</ValidateRingProfileFromFile>

Response:

<ValidateRingProfileFromFile>
  <Type value="SingleAddress"/>
  <Input path="s:/solocast/BgTest.csv" format="0"/>
  <RootName value="Custom Radius Profile Set"/>
  <Radius value="5"/>
  <Units value="Miles"/>
  <Fields>
    <Field name="name" type="name" fieldNumber=""/>
    <Field name="address" type="address" fieldNumber=""/>
    <Field name="LAST_LINE" type="city" fieldNumber=""/>
  </Fields>
  <OutputScdFile path="s:/solocast/Custom Radius Profile Set.scd"/>
  <Commands count="3">
    <Commands value="In_Geography(&quot;PointFileEx&quot;,&quot;s:/solocast/BgTest.csv&quot;,&quot;&quot;, 
  &quot;0&quot;,&quot;name&quot;,&quot;name&quot;,&quot;PointAddress&quot;,&quot;address&quot;, 
  &quot;LAST_LINE&quot;,&quot;&quot;,&quot;&quot;,&quot;5&quot;, &quot;Miles&quot;,false)"/>
    <Commands value="Output_FilePath(&quot;s:/solocast/Custom Radius Profile Set.scd&quot;)"/>
    <Commands value="Base(&quot;None&quot;)"/>
  </Commands>
</ValidateRingProfileFromFile>

Errors in Response:

Error Elements may be returned in the following cases:

1. Required attributes could not be found.  They will be named.
2. The information provided was not sufficient to validate the commands.
3. The Type element value is not either "CensusCluster" or "Demographic".

ValidateRingProfileFromLatLon

Purpose:

This encapsulates validating a new ring profile using the current new profile api.   Given the information required to build a Profile Set based upon a latitude and longitude location, the response returns the Commands that may be included in the Solocast workspace command that actually builds the Profile Set.

This request simply validates and formats Command strings that may be submitted to the Solocast engine using the appropriate CreateNewProfile API.

Request DTD:

<?xml version="1.0" encoding="UTF-8"?>
<!-- DTD for ValidateRingProfileFromLatLon Request -->
<!ELEMENT ValidateRingProfileFromLatLon (Name,Lat,Lon,Radius,Units,OutputScdFile,(Base|ProfileBase)?)>
<!ELEMENT Name EMPTY>
  <!ATTLIST Name value CDATA #REQUIRED>
<!ELEMENT Lat EMPTY>
  <!ATTLIST Lat value CDATA #REQUIRED>
<!ELEMENT Lon EMPTY>
  <!ATTLIST Lon value CDATA #REQUIRED>
<!ELEMENT Radius EMPTY>
  <!ATTLIST Radius value CDATA #REQUIRED>
<!ELEMENT Units EMPTY>
  <!ATTLIST Units value (Miles|Kilometers|Minutes) #REQUIRED>
<!ELEMENT OutputScdFile EMPTY>
  <!ATTLIST OutputScdFile path CDATA #REQUIRED>
  <!ATTLIST OutputScdFile append CDATA #IMPLIED>
<!ELEMENT Base EMPTY>
  <!ATTLIST Base value (None|Automatic) #REQUIRED>
<!ELEMENT ProfileBase EMPTY>
  <!ATTLIST ProfileBase path CDATA #REQUIRED>
  <!ATTLIST ProfileBase name CDATA #REQUIRED>

Request Schema:

<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <xsd:element name="Name">
    <xsd:complexType>
      <xsd:attribute name="value" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="Units">
    <xsd:complexType>
      <xsd:attribute name="value" use="required" type="Unitsvaluetype"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="Lat">
    <xsd:complexType>
      <xsd:attribute name="value" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="OutputScdFile">
    <xsd:complexType>
      <xsd:attribute name="path" use="required" type="xsd:string"/>
      <xsd:attribute name="append" default="" use="optional" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="Lon">
    <xsd:complexType>
      <xsd:attribute name="value" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="ProfileBase">
    <xsd:complexType>
      <xsd:attribute name="path" use="required" type="xsd:string"/>
      <xsd:attribute name="name" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="ValidateRingProfileFromLatLon">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element ref="Name"/>
        <xsd:element ref="Lat"/>
        <xsd:element ref="Lon"/>
        <xsd:element ref="Radius"/>
        <xsd:element ref="Units"/>
        <xsd:element ref="OutputScdFile"/>
        <xsd:choice>
          <xsd:element ref="Base"/>
          <xsd:element ref="ProfileBase"/>
        </xsd:choice>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="Radius">
    <xsd:complexType>
      <xsd:attribute name="value" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="Base">
    <xsd:complexType>
      <xsd:attribute name="value" use="required" type="Basevaluetype"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:simpleType name="Basevaluetype">
    <xsd:restriction base="xsd:string">
      <xsd:enumeration value="None"/>
      <xsd:enumeration value="Automatic"/>
    </xsd:restriction>
  </xsd:simpleType>
  <xsd:simpleType name="Unitsvaluetype">
    <xsd:restriction base="xsd:string">
      <xsd:enumeration value="Miles"/>
      <xsd:enumeration value="Kilometers"/>
      <xsd:enumeration value="Minutes"/>
    </xsd:restriction>
  </xsd:simpleType>
</xsd:schema>

Code Example:

const char *pXmlResponse;
const char * pMultiRingFromLatLonXml = 
"<ValidateRingProfileFromLatLon>\n"
" <Name value=\"Office\"/>\n"
" <Lat value=\"40.022853\"/>\n"
" <Lon value=\"-105.281088\"/>\n"
" <Radius value=\"4\"/>\n"
" <Units value=\"Miles\"/>\n"
" <OutputScdFile path=\"s:/solocast/OfficeMultiRadius.scd\"/>\n"
"</ValidateRingProfileFromLatLon>\n";
printf("Test ValidateRingProfileFromLatLon\n%s\n", pMultiRingFromLatLonXml);
char defaultbuffer[256];
int defaulthandle = SC_Open("", defaultbuffer);
if (defaulthandle < 1)
{
	printf("Bad Handle: Could not open Solocast (handle = %d)\n", defaulthandle);
	exit(0);
}
pXmlResponse = SC_GetPropertiesString(defaulthandle, pMultiRingFromLatLonXml);
SC_Close(defaulthandle );

Request:

<ValidateRingProfileFromLatLon>
  <Name value="Office"/>
  <Lat value="40.022853"/>
  <Lon value="-105.281088"/>
  <Radius value="4"/>
  <Units value="Miles"/>
  <OutputScdFile path="s:/solocast/OfficeMultiRadius.scd"/>
</ValidateRingProfileFromLatLon>

Response:

<ValidateRingProfileFromLatLon>
  <Name value="Office"/>
  <Lat value="40.022853"/>
  <Lon value="-105.281088"/>
  <Radius value="4"/>
  <Units value="Miles"/>
  <OutputScdFile path="s:/solocast/OfficeMultiRadius.scd"/>
  <Commands count="3">
    <Commands value="In_Geography(&quot;Radius&quot;,40.022853,-105.281088,&quot;4&quot;,&quot;Office&quot;,&quot;Miles&quot;)"/>
    <Commands value="Output_FilePath(&quot;s:/solocast/OfficeMultiRadius.scd&quot;)"/>
    <Commands value="Base(&quot;None&quot;)"/>
  </Commands>
</ValidateRingProfileFromLatLon>

Errors in Response:

Error Elements may be returned in the following cases:

1. Required attributes could not be found.  They will be named.
2. The information provided was not sufficient to validate the commands.
3. The Type element value is not either "CensusCluster" or "Demographic".

ValidateRegionProfile

Purpose:

This encapsulates validating a new polygon profile using the current new profile api.    Given the information required to build a Profile Set based upon Polygon information, the response returns the Commands that may be included in the Solocast workspace command that actually builds the Profile Set.

This request simply validates and formats Command strings that may be submitted to the Solocast engine using the appropriate CreateNewProfile API.

Request DTD:

<?xml version="1.0" encoding="UTF-8"?>
<!-- DTD for ValidateRegionProfile Request -->
<!ELEMENT ValidateRegionProfile (Input,Fields,OutputScdFile,(Base|ProfileBase)?)>
<!ELEMENT Input EMPTY>
  <!ATTLIST Input path CDATA #REQUIRED>
  <!ATTLIST Input format CDATA #REQUIRED>
<!ELEMENT Fields (Field+)>
<!ELEMENT Field EMPTY>
  <!ATTLIST Field type (name) #REQUIRED>
  <!ATTLIST Field name CDATA #REQUIRED>
  <!ATTLIST Field fieldNumber CDATA #IMPLIED>
<!ELEMENT OutputScdFile EMPTY>
  <!ATTLIST OutputScdFile path CDATA #REQUIRED>
  <!ATTLIST OutputScdFile append CDATA #IMPLIED>
  <!ATTLIST OutputScdFile summarize (true|false) #IMPLIED>
<!ELEMENT Base EMPTY>
  <!ATTLIST Base value (None|Automatic) #REQUIRED>
<!ELEMENT ProfileBase EMPTY>
  <!ATTLIST ProfileBase path CDATA #REQUIRED>
  <!ATTLIST ProfileBase name CDATA #REQUIRED>

Request Schema:

<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <xsd:element name="OutputScdFile">
    <xsd:complexType>
      <xsd:attribute name="summarize" default="" use="optional" type="OutputScdFilesummarizetype"/>
      <xsd:attribute name="path" use="required" type="xsd:string"/>
      <xsd:attribute name="append" default="" use="optional" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="Field">
    <xsd:complexType>
      <xsd:attribute name="fieldNumber" default="" use="optional" type="xsd:string"/>
      <xsd:attribute name="type" use="required" type="Fieldtypetype"/>
      <xsd:attribute name="name" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="Input">
    <xsd:complexType>
      <xsd:attribute name="format" use="required" type="xsd:string"/>
      <xsd:attribute name="path" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="Fields">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element ref="Field" minOccurs="1" maxOccurs="unbounded"/>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="ProfileBase">
    <xsd:complexType>
      <xsd:attribute name="path" use="required" type="xsd:string"/>
      <xsd:attribute name="name" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="ValidateRegionProfile">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element ref="Input"/>
        <xsd:element ref="Fields"/>
        <xsd:element ref="OutputScdFile"/>
        <xsd:choice>
          <xsd:element ref="Base"/>
          <xsd:element ref="ProfileBase"/>
        </xsd:choice>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="Base">
    <xsd:complexType>
      <xsd:attribute name="value" use="required" type="Basevaluetype"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:simpleType name="Basevaluetype">
    <xsd:restriction base="xsd:string">
      <xsd:enumeration value="None"/>
      <xsd:enumeration value="Automatic"/>
    </xsd:restriction>
  </xsd:simpleType>
  <xsd:simpleType name="Fieldtypetype">
    <xsd:restriction base="xsd:string">
      <xsd:enumeration value="name"/>
    </xsd:restriction>
  </xsd:simpleType>
  <xsd:simpleType name="OutputScdFilesummarizetype">
    <xsd:restriction base="xsd:string">
      <xsd:enumeration value="true"/>
      <xsd:enumeration value="false"/>
    </xsd:restriction>
  </xsd:simpleType>
</xsd:schema>

Code Example:

const char *pXmlResponse ;
const char * pCreateInRegion = 
"<ValidateRegionProfile>\n"
" <Input path=\"s:/solocast/Hartford DMA Zips.tab\" format=\"11\"/>\n"
" <Fields>\n"
" <Field type=\"name\" name=\"NAME\" fieldNumber=\"\"/>\n"
" </Fields>\n"
" <OutputScdFile path=\"s:/solocast/InRegion.scd\"/>\n"
"</ValidateRegionProfile>\n";
printf("Test ValidateRegionProfile\n%s\n", pCreateInRegion);
char defaultbuffer[256];
int defaulthandle = SC_Open("", defaultbuffer);
if (defaulthandle < 1)
{
	printf("Bad Handle: Could not open Solocast (handle = %d)\n", defaulthandle);
	exit(0);
}
pXmlResponse = SC_GetPropertiesString(defaulthandle, pCreateInRegion);
SC_Close(defaulthandle );

Request:

<ValidateRegionProfile>
  <Input path="s:/solocast/Hartford DMA Zips.tab" format="11"/>
  <Fields>
    <Field type="name" name="NAME" fieldNumber=""/>
  </Fields>
  <OutputScdFile path="s:/solocast/InRegion.scd"/>
</ValidateRegionProfile>

Response:

<ValidateRegionProfile>
  <Input path="s:/solocast/Hartford DMA Zips.tab" format="11"/>
  <Fields>
    <Field name="NAME" type="name" fieldNumber=""/>
  </Fields>
  <OutputScdFile path="s:/solocast/InRegion.scd"/>
  <Commands count="3">
    <Commands value="In_Geography(&quot;PolygonFile&quot;,&quot;s:/solocast/Hartford DMA Zips.tab&quot;, &quot;11&quot;, &quot;NAME&quot;)"/>
    <Commands value="Output_FilePath(&quot;s:/solocast/InRegion.scd&quot;)"/>
    <Commands value="Base(&quot;None&quot;)"/>
  </Commands>
</ValidateRegionProfile>

Errors in Response:

Error Elements may be returned in the following cases:

1. Required attributes could not be found.  They will be named.
2. The information provided was not sufficient to validate the commands.
3. The Type element value is not either "CensusCluster" or "Demographic".

GetTargetClusters

Purpose:

Enumerates the available clusters.  The key, Major Group and description of each cluster is returned.

In the response, the Clusters element contains the clusters in sorted order.  Please note, the Cluster element with index = 0 is an internal cluster that identifies the source of the segmentation data.

In the response, following the Clusters information, are the Groupings.  Each Grouping within the Groupings element contains a description.  There may be several Grouping elements.  Each Grouping element itself contains one or more Group elements.  The Group elements contain Cluster elements, each an index that refers back to the Cluster elements in initial Clusters element.

In our example below, the Segmentation is broken into Mosiac Groups and Global Mosiac Groups Groupings.  Depending on the need you might look at the Clustering element, the Mosiac Groups Grouping or the Global Mosiac Groups Grouping, and populate a list or combo box accordingly.

Code Example:

const char *pXmlResponse ;
const char * pTargetClusters = 
"<GetTargetClusters>\n"
"</GetTargetClusters>\n";
printf("Test GetTargetClusters\n%s\n", pTargetClusters);
char defaultbuffer[256];
int defaulthandle = SC_Open("", defaultbuffer);
if (defaulthandle < 1)
{
    printf("Bad Handle: Could not open Solocast (handle = %d)\n", defaulthandle);
    exit(0);
}
pXmlResponse = SC_GetPropertiesString(defaulthandle, pTargetClusters);
SC_Close(defaulthandle );

Request:

<GetTargetClusters>
</GetTargetClusters>

Response:

<GetTargetClusters>
  <Clusters count="63">
    <Cluster desc="(C) 2002 Applied Geographic Solutions, Inc. All Rights Reserved." index="0"/>
    <Cluster desc="A01: Very high-income,families w older children,suburban areas" index="1"/>
    <Cluster desc="A02: Very high-income,large families in suburban areas" index="2"/>
    <Cluster desc="A03: Very high-income,young,suburban families with children" index="3"/>
    <Cluster desc="A04: Empty-nest,high-income,suburban couples" index="4"/>
    <Cluster desc="A05: High-income,families with older children in suburban areas" index="5"/>
    <Cluster desc="A06: Large,high-income families in major market suburbs" index="6"/>
    <Cluster desc="A07: High-income families with children in suburbs" index="7"/>
    <Cluster desc="A08: Suburban,high-income families with older children" index="8"/>
    <Cluster desc="B09: High-income,urban singles in apartments" index="9"/>
    <Cluster desc="B10: Urban,upper-mid-income,seniors in apartments" index="10"/>
    <Cluster desc="B11: Mid-income,educated,apartment dwellers in major metro areas" index="11"/>
    <Cluster desc="B12: Upper-mid-income sngls &amp; cpls in growth-city houses or apts" index="12"/>
    <Cluster desc="B13: Young,lower-mid-income,educated singles in urban apts" index="13"/>
    <Cluster desc="B14: Urban,upper-mid-income families with children" index="14"/>
    <Cluster desc="C15: High-income families in satellite cities" index="15"/>
    <Cluster desc="C16: Sunbelt,upper-mid-income,white-collar families w children" index="16"/>
    <Cluster desc="C17: Educated,mid-income families in fringe areas" index="17"/>
    <Cluster desc="C18: Mixed-housing,lower-mid-inc,small towns mainly New England" index="18"/>
    <Cluster desc="C19: Mid-income couples and singles in smaller tows" index="19"/>
    <Cluster desc="D20: Upper-mid-income,homeowner fams,mainly Northern states" index="20"/>
    <Cluster desc="D21: Suburban,upper-mid-income,blue collar families" index="21"/>
    <Cluster desc="D22: Suburban,mid-income,blue-collar families with children" index="22"/>
    <Cluster desc="D23: Young,mid-income,blue-collar families with children,Sunbelt" index="23"/>
    <Cluster desc="D24: Lower-mid-income families in suburbs and small towns" index="24"/>
    <Cluster desc="E25: Older,mid-income families mainly in coastal areas" index="25"/>
    <Cluster desc="E26: Older,high-income families mainly in Northeast" index="26"/>
    <Cluster desc="E27: Mid-income,older couples in small cities" index="27"/>
    <Cluster desc="E28: Lower-income,older,blue-collar couples,many in mobile homes" index="28"/>
    <Cluster desc="E29: Older,lower-mid-inc,wht-coll cpls mainly in Gr Lakes towns" index="29"/>
    <Cluster desc="E30: Older,lower-mid-inc,bl-coll cpls,small town,sngl-famly homes" index="30"/>
    <Cluster desc="F31: Low income,well-educated,young singles in apartments" index="31"/>
    <Cluster desc="F32: West coast,upper-mid-inc fams,predom Asian/Pacific Islanders" index="32"/>
    <Cluster desc="F33: Mid-inc,multi-ethnic apt dwllrs,mainly Mid-Atl metro fringes" index="33"/>
    <Cluster desc="F34: Lower-mid-income,blue-collar apt dwellers in metro fringes" index="34"/>
    <Cluster desc="F35: Large,mid-income,blue-collar families,predominantly Hispanic" index="35"/>
    <Cluster desc="G36: Lower-mid-inc,older,bl-coll fams mainly Appalachia &amp; S.East" index="36"/>
    <Cluster desc="G37: Lower-mid-inc,older,bl-coll fams mainly Gr Lakes &amp; New Eng" index="37"/>
    <Cluster desc="G38: Lower-inc,blue-collar,mixed dwelling types predom Sunbelt" index="38"/>
    <Cluster desc="H39: Lower-income,older sngls &amp; cpls in small city mixed housing" index="39"/>
    <Cluster desc="H40: Lower-income,older singles &amp; couples in urban apartments" index="40"/>
    <Cluster desc="H41: Lower-mid-income,older sngls &amp; cpls in urban houses &amp; apts" index="41"/>
    <Cluster desc="H42: Lower-inc,older sngls &amp; cpls mainly in small Midwest towns" index="42"/>
    <Cluster desc="I43: Lower-mid-income,farm families mainly in the Great Plains" index="43"/>
    <Cluster desc="I44: Lower-income,agricultural families with children" index="44"/>
    <Cluster desc="I45: Lower-income,rural,blue-collar families with children" index="45"/>
    <Cluster desc="I46: Lower-income,rural families w children mainly in the South" index="46"/>
    <Cluster desc="I47: Lower-inc,young,blue-collar families,mainly Southwest" index="47"/>
    <Cluster desc="I48: Lower-inc,bl-coll fams in mobile homes,mainly in the South" index="48"/>
    <Cluster desc="J49: Predom African-Amer,lower-mid-inc fams,mainly Southern city" index="49"/>
    <Cluster desc="J50: Multi-ethnic,lower-inc,bl-coll sgls,mainly Sunbelt urb core" index="50"/>
    <Cluster desc="J51: Lower-mid-incm,blue-collar sngls,Northeastern urban cores" index="51"/>
    <Cluster desc="J52: Lower-income,blue-collar families in smaller towns" index="52"/>
    <Cluster desc="J53: Lower-inc,mostly lrg Hispanic or Natv Amer fams,rural areas" index="53"/>
    <Cluster desc="J54: Predom African-Amer,low-incm fams w chldrn,mainly in South" index="54"/>
    <Cluster desc="K55: Predom African-Amer,lower-mid-inc mixed dwl types,urb cores" index="55"/>
    <Cluster desc="K56: Multi-ethnic,young,lower-incm renters in small urban areas" index="56"/>
    <Cluster desc="K57: Predom Hispanic,lower-mid-incm larger fams,mainly in So Cal" index="57"/>
    <Cluster desc="K58: Predom Hispanic,lower-incm fams,mainly New York metro area" index="58"/>
    <Cluster desc="K59: Predom African-Amer,lower-incm,sngl-par fams,industl cities" index="59"/>
    <Cluster desc="K60: Predom African-Amer,very low-incm,sngl-par fams in the city" index="60"/>
    <Cluster desc="L61: Lower-mid-income,residential quarters of military personnel" index="61"/>
    <Cluster desc="L62: Lower-income,college residential areas and dormitories" index="62"/>
  </Clusters>
  <Groupings count="2">
    <Grouping desc="Mosaic Groups" count="13">
      <Group desc="Affluent Suburbia" index="0">
        <Cluster key="1"/>
        <Cluster key="2"/>
        <Cluster key="3"/>
        <Cluster key="4"/>
        <Cluster key="5"/>
        <Cluster key="6"/>
        <Cluster key="7"/>
        <Cluster key="8"/>
      </Group>
      <Group desc="Upscale City Singles" index="1">
        <Cluster key="9"/>
        <Cluster key="10"/>
        <Cluster key="11"/>
        <Cluster key="12"/>
        <Cluster key="13"/>
        <Cluster key="14"/>
      </Group>
      <Group desc="Second City Leaders" index="2">
        <Cluster key="15"/>
        <Cluster key="16"/>
        <Cluster key="17"/>
        <Cluster key="18"/>
        <Cluster key="19"/>
      </Group>
      <Group desc="Blue Collar Winners" index="3">
        <Cluster key="20"/>
        <Cluster key="21"/>
        <Cluster key="22"/>
        <Cluster key="23"/>
        <Cluster key="24"/>
      </Group>
      <Group desc="Fortunate Retirees" index="4">
        <Cluster key="25"/>
        <Cluster key="26"/>
        <Cluster key="27"/>
        <Cluster key="28"/>
        <Cluster key="29"/>
        <Cluster key="30"/>
      </Group>
      <Group desc="Metro Market Fringes" index="5">
        <Cluster key="31"/>
        <Cluster key="32"/>
        <Cluster key="33"/>
        <Cluster key="34"/>
        <Cluster key="35"/>
      </Group>
      <Group desc="Remote Working Towns" index="6">
        <Cluster key="36"/>
        <Cluster key="37"/>
        <Cluster key="38"/>
      </Group>
      <Group desc="Low Income Seniors" index="7">
        <Cluster key="39"/>
        <Cluster key="40"/>
        <Cluster key="41"/>
        <Cluster key="42"/>
      </Group>
      <Group desc="Rural Towns &amp; Farms" index="8">
        <Cluster key="43"/>
        <Cluster key="44"/>
        <Cluster key="45"/>
        <Cluster key="46"/>
        <Cluster key="47"/>
        <Cluster key="48"/>
      </Group>
      <Group desc="Other City Centers" index="9">
        <Cluster key="49"/>
        <Cluster key="50"/>
        <Cluster key="51"/>
        <Cluster key="52"/>
        <Cluster key="53"/>
        <Cluster key="54"/>
      </Group>
      <Group desc="Major Market Cores" index="10">
        <Cluster key="55"/>
        <Cluster key="56"/>
        <Cluster key="57"/>
        <Cluster key="58"/>
        <Cluster key="59"/>
        <Cluster key="60"/>
      </Group>
      <Group desc="Anomalous Lifestyles" index="11">
        <Cluster key="61"/>
        <Cluster key="62"/>
      </Group>
      <Group desc="N/A" index="12"/>
    </Grouping>
    <Grouping desc="Global Mosaic Groups" count="14">
      <Group desc="Agrarian Heartlands" index="0">
        <Cluster key="43"/>
        <Cluster key="44"/>
        <Cluster key="45"/>
      </Group>
      <Group desc="Blue Collar Self Sufficiency" index="1">
        <Cluster key="20"/>
        <Cluster key="21"/>
        <Cluster key="22"/>
        <Cluster key="23"/>
        <Cluster key="30"/>
        <Cluster key="38"/>
        <Cluster key="48"/>
      </Group>
      <Group desc="Career Focused Materialists" index="2">
        <Cluster key="3"/>
        <Cluster key="6"/>
        <Cluster key="7"/>
        <Cluster key="15"/>
      </Group>
      <Group desc="Deindustrial Legacy" index="3">
        <Cluster key="37"/>
        <Cluster key="47"/>
      </Group>
      <Group desc="Educated Cosmopolitans" index="4">
        <Cluster key="5"/>
        <Cluster key="9"/>
        <Cluster key="10"/>
        <Cluster key="11"/>
        <Cluster key="12"/>
        <Cluster key="13"/>
        <Cluster key="17"/>
        <Cluster key="31"/>
      </Group>
      <Group desc="Farming Town Communities" index="5">
        <Cluster key="24"/>
        <Cluster key="36"/>
        <Cluster key="46"/>
        <Cluster key="53"/>
      </Group>
      <Group desc="Greys Blue Sea &amp; Mountain" index="6">
        <Cluster key="18"/>
        <Cluster key="25"/>
        <Cluster key="28"/>
      </Group>
      <Group desc="Hardened Dependency" index="7">
        <Cluster key="58"/>
        <Cluster key="59"/>
        <Cluster key="60"/>
      </Group>
      <Group desc="Inner City Melting Pot" index="8">
        <Cluster key="35"/>
        <Cluster key="49"/>
        <Cluster key="50"/>
        <Cluster key="51"/>
        <Cluster key="52"/>
        <Cluster key="54"/>
        <Cluster key="55"/>
        <Cluster key="56"/>
        <Cluster key="57"/>
      </Group>
      <Group desc="Lower Income Elderly" index="9">
        <Cluster key="39"/>
        <Cluster key="40"/>
        <Cluster key="41"/>
        <Cluster key="42"/>
      </Group>
      <Group desc="Midscale Metro Office Workers" index="10">
        <Cluster key="14"/>
        <Cluster key="16"/>
        <Cluster key="19"/>
        <Cluster key="29"/>
        <Cluster key="32"/>
        <Cluster key="33"/>
        <Cluster key="34"/>
      </Group>
      <Group desc="Non-Private Residences" index="11">
        <Cluster key="61"/>
        <Cluster key="62"/>
      </Group>
      <Group desc="Old Wealth" index="12">
        <Cluster key="1"/>
        <Cluster key="2"/>
        <Cluster key="4"/>
        <Cluster key="8"/>
        <Cluster key="26"/>
        <Cluster key="27"/>
      </Group>
      <Group desc="N/A" index="13"/>
    </Grouping>
  </Groupings>
</GetTargetClusters>

RunProfileDetailReport

Purpose:

RunProfileDetailReport generates a profile detail report to the browser.  This is analogous to generating a detail report from the Solocast desktop application.  The demographicVar attribute is optional.  If it is not supplied then “1” is defaulted, which maps to households.  The profile detail report is a report by cluster group of a selected Profile.  Presumably a call to GetProfileSets and GetProfilesWithinProfileSet has preceeded this request.

There currently is not a way to save this report to a file, it will always come up in a browser.

Request DTD:

<?xml version="1.0" encoding="UTF-8"?>
<!-- DTD for RunProfileDetailReport Request -->
<!ELEMENT RunProfileDetailReport (Profile)>
<!ELEMENT Profile EMPTY>
  <!ATTLIST Profile name CDATA #REQUIRED>
  <!ATTLIST Profile path CDATA #REQUIRED>
  <!ATTLIST Profile demographicVar CDATA #IMPLIED>

Request Schema:

<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <xsd:element name="Profile">
    <xsd:complexType>
      <xsd:attribute name="path" use="required" type="xsd:string"/>
      <xsd:attribute name="name" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="RunProfileDetailReport">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element ref="Profile"/>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
</xsd:schema>

Code Example:

In this example, we create a Cluster Report of "People who Ate Fast Food 14+ Times in the last 30 Days".  

const char *pXmlResponse ;
const char * pWorkspaceDetailReportXml = 
"<RunProfileDetailReport>\n"
" <Profile path=\"s:/solocast/Sample.SCD\" name=\"Ate Fast Food 14+ Times In Last 30 Days\"/>\n"
"</RunProfileDetailReport>\n";
printf("Test RunProfileDetailReport\n%s\n", pWorkspaceDetailReportXml);
char defaultbuffer[256];
int defaulthandle = SC_Open("", defaultbuffer);
if (defaulthandle < 1)
{
    printf("Bad Handle: Could not open Solocast (handle = %d)\n", defaulthandle);
    exit(0);
}
pXmlResponse = SC_GetPropertiesString(defaulthandle, pWorkspaceDetailReportXml);
SC_Close(defaulthandle );

Request:

<RunProfileDetailReport>
  <Profile path="s:/solocast/Sample.SCD" name="Ate Fast Food 14+ Times In Last 30 Days"/>
</RunProfileDetailReport>

Response:

<RunProfileDetailReport>
  <Profile name="Ate Fast Food 14+ Times In Last 30 Days" path="s:/solocast/Sample.SCD"/>
</RunProfileDetailReport>

Errors in Response:

Error Elements may be returned in the following cases:

1. Required attributes could not be found.  They will be named.
2. The Profile Set specified could not be found.
3. The Profile within the specified Profile Set 

GetDemographicTypes

Purpose:

 Each dataset has a unique way of arranging its Demographic Variables.  If you are creating a report which requires specifying the Household Demographic Variable, you need a way to determine which one it is.  To do so, use the GetDemographicTypes property to identify the 

Code Example:

const char *pXmlResponse ;
const char * pGetDemoTypes = 
"<GetDemographicTypes>\n"
"</GetDemographicTypes>\n";
printf("Test GetDemographicTypes\n%s\n", pGetDemoTypes );
char defaultbuffer[256];
int defaulthandle = SC_Open("", defaultbuffer);
if (defaulthandle < 1)
{
    printf("Bad Handle: Could not open Solocast (handle = %d)\n", defaulthandle);
    exit(0);
}
pXmlResponse = SC_GetPropertiesString(defaulthandle, pGetDemoTypes );
SC_Close(defaulthandle );

Request:

<GetDemographicTypes >
</GetDemographicTypes >

Response:

<GetDemographicTypes count="5">
  <Household key="1" desc="2001 Total Households"/>
  <Type key="0" desc="Female Population"/>
  <Type key="1" desc="Male Population"/>
  <Type key="2" desc="Total Population"/>
  <Type key="3" desc="Age 18+"/>
  <Type key="4" desc="2001 Total Households"/>
</GetDemographicTypes>

Errors in Response:

There are no abnormal errors.

Unknown Request

Purpose:

Generating a request that is not known (typographical usually) will generate an Error node whose reason attribute is "Unknown Request".  We do not bother returning the the actual request in error, it is part of the response.

Code Example:

const char *pXmlResponse;
const char * pUnknownRequest = 
"<AnyOtherRequest>\n"
"</AnyOtherRequest>\n";
printf("Test RunProfileDetailReport\n%s\n", pWorkspaceDetailReportXml);
char defaultbuffer[256];
int defaulthandle = SC_Open("", defaultbuffer);
if (defaulthandle < 1)
{
    printf("Bad Handle: Could not open Solocast (handle = %d)\n", defaulthandle);
    exit(0);
}
pXmlResponse = SC_GetPropertiesString(defaulthandle, pWorkspaceDetailReportXml);
SC_Close(defaulthandle );

Request:

The following request could be anything not covered in this document.

<AnyOtherRequest>
</AnyOtherRequest>

Response:

<AnyOtherRequest>
  <Error reason="Unknown Request"/>
</AnyOtherRequest>