Skip to Main Content
Organization Title

API Reference

Geocode & Shortage Designations

Geocode Web service is designed get an address's geographic coordinates. This method can also be used to validate and standardize an address even if you don't need geographic coordinates. This web service is also able to return health profession shortage designations of an address that is of California.

Geocode web service takes a full or partial address string and returns a matching address sorted by best match in JSON format.

Below is an example web service URL with some parameters.

http://geo.oshpd.ca.gov/service/geocode?key=YOUR_KEY_HERE&findshortagedesignations=true&address=400+R+St+Sacramento+CA&calreachdoctype=

Parameters

key (required)
An api key must be provided to use this service. Contact ITSD's Manraj Singh to obtain a key.
address (required)
Input address
maxlocations
Returns requested number of locations matching the search criteria. Currently it is capped at 10 locations per search and default is 5.
findshortagedesignations
When set to true, reponse will include shortage designations for each address returned in response.
calreachdoctype
Given this parameter, the Area of Unmet Need (in_umn) flag may be determined differently. Currently SongBrown program may require this flag to be computed differently for various programs. For Example, An address's Area of Unmet Need flag(in_umn) Registered Nurse Special Program's application doesn't care about any other flags other than Registered Nurse Shortage Area (rnsa).

Json Response

{
	response: "success",
	addresses: [
		{
			ExtensionData: { },
			Attributes: {
				ExtensionData: { },
				AddressPrecision: "ROOFTOP",
				AddressType: "street_address",
				Source: "Google"
			},
			City: "Sacramento",
			County: "Sacramento",
			FullAddress: "400 R St, Sacramento, CA 95811",
			Latitude: 38.5732617,
			Longitude: -121.5047861,
			ShortageDesignations: {
				ExtensionData: { },
				census_tract: "21",
				central_valley: true,
				endowment_communities: false,
				hpsa_dc: false,
				hpsa_dc_date: "",
				hpsa_dc_id: null,
				hpsa_dc_score: 0,
				hpsa_mh: false,
				hpsa_mh_date: "",
				hpsa_mh_id: null,
				hpsa_mh_score: 0,
				hpsa_pc: true,
				hpsa_pc_date: "8/18/2011 12:00:00 AM",
				hpsa_pc_id: "10699906PK",
				hpsa_pc_score: 14,
				in_umn: true,
				mssa_definition: "Urban",
				mssa_id: "139j",
				mua: false,
				mup: false,
				pcsa: true,
				rnsa: true
			},
			State: "CA",
			Street: "400 R St",
			Zipcode: "95811"
		}
	]
}

Geocode service may return multiple addresses if a partial address was given. Below is a an example of that

http://geo.oshpd.ca.gov/service/geocode?key=YOUR_KEY_HERE&findshortagedesignations=true&address=400+R+Street
{
	addresses: [
		{
			ExtensionData: { },
			Attributes: {
				ExtensionData: { },
				AddressPrecision: "RANGE_INTERPOLATED",
				AddressType: "street_address",
				Source: "Google"
			},
			City: "Merced",
			County: "Merced",
			FullAddress: "400 R St, Merced, CA 95341",
			Latitude: 37.2914709,
			Longitude: -120.5000127,
			ShortageDesignations: {
				ExtensionData: { },
				census_tract: "15.03",
				central_valley: true,
				endowment_communities: true,
				hpsa_dc: false,
				hpsa_dc_date: "",
				hpsa_dc_id: null,
				hpsa_dc_score: 0,
				hpsa_mh: true,
				hpsa_mh_date: "5/20/1996 12:00:00 AM",
				hpsa_mh_id: "706047",
				hpsa_mh_score: 18,
				hpsa_pc: true,
				hpsa_pc_date: "6/4/2009 12:00:00 AM",
				hpsa_pc_id: "10699906MJ",
				hpsa_pc_score: 7,
				in_umn: true,
				mssa_definition: "Rural",
				mssa_id: "97.2",
				mua: false,
				mup: false,
				pcsa: true,
				rnsa: true
			},
			State: "CA",
			Street: "400 R St",
			Zipcode: "95341"
		},
		{
			ExtensionData: { },
			Attributes: {
				ExtensionData: { },
				AddressPrecision: "ROOFTOP",
				AddressType: "street_address",
				Source: "Google"
			},
			City: "Sacramento",
			County: "Sacramento",
			FullAddress: "400 R St, Sacramento, CA 95811",
			Latitude: 38.5732617,
			Longitude: -121.5047861,
			ShortageDesignations: {
				ExtensionData: { },
				census_tract: "21",
				central_valley: true,
				endowment_communities: false,
				hpsa_dc: false,
				hpsa_dc_date: "",
				hpsa_dc_id: null,
				hpsa_dc_score: 0,
				hpsa_mh: false,
				hpsa_mh_date: "",
				hpsa_mh_id: null,
				hpsa_mh_score: 0,
				hpsa_pc: true,
				hpsa_pc_date: "8/18/2011 12:00:00 AM",
				hpsa_pc_id: "10699906PK",
				hpsa_pc_score: 14,
				in_umn: true,
				mssa_definition: "Urban",
				mssa_id: "139j",
				mua: false,
				mup: false,
				pcsa: true,
				rnsa: true
			},
			State: "CA",
			Street: "400 R St",
			Zipcode: "95811"
		},
		{
			ExtensionData: { },
			Attributes: {
				ExtensionData: { },
				AddressPrecision: "RANGE_INTERPOLATED",
				AddressType: "street_address",
				Source: "Google"
			},
			City: "Bakersfield",
			County: "Kern",
			FullAddress: "400 R St, Bakersfield, CA 93304",
			Latitude: 35.3607753,
			Longitude: -119.0095298,
			ShortageDesignations: {
				ExtensionData: { },
				census_tract: "20",
				central_valley: true,
				endowment_communities: false,
				hpsa_dc: false,
				hpsa_dc_date: "",
				hpsa_dc_id: null,
				hpsa_dc_score: 0,
				hpsa_mh: true,
				hpsa_mh_date: "9/16/2013 12:00:00 AM",
				hpsa_mh_id: "706999061I",
				hpsa_mh_score: 14,
				hpsa_pc: false,
				hpsa_pc_date: "",
				hpsa_pc_id: null,
				hpsa_pc_score: 0,
				in_umn: true,
				mssa_definition: "Urban",
				mssa_id: "66b",
				mua: true,
				mup: false,
				pcsa: true,
				rnsa: true
			},
			State: "CA",
			Street: "400 R St",
			Zipcode: "93304"
		},
		{
			ExtensionData: { },
			Attributes: {
				ExtensionData: { },
				AddressPrecision: "RANGE_INTERPOLATED",
				AddressType: "street_address",
				Source: "Google"
			},
			City: "Lincoln",
			County: "Placer",
			FullAddress: "400 R St, Lincoln, CA 95648",
			Latitude: 38.8905672,
			Longitude: -121.3081162,
			ShortageDesignations: {
				ExtensionData: { },
				census_tract: "214.03",
				central_valley: false,
				endowment_communities: false,
				hpsa_dc: false,
				hpsa_dc_date: "",
				hpsa_dc_id: null,
				hpsa_dc_score: 0,
				hpsa_mh: false,
				hpsa_mh_date: "",
				hpsa_mh_id: null,
				hpsa_mh_score: 0,
				hpsa_pc: false,
				hpsa_pc_date: "",
				hpsa_pc_id: null,
				hpsa_pc_score: 0,
				in_umn: false,
				mssa_definition: "Rural",
				mssa_id: "119",
				mua: false,
				mup: false,
				pcsa: false,
				rnsa: false
			},
			State: "CA",
			Street: "400 R St",
			Zipcode: "95648"
		}
	],
	response: "success"
}

Geocode service may not be able to find an address matching the input. Below is an example of how that is handled and reported.

http://geo.oshpd.ca.gov/service/geocode?key=YOUR_KEY_HERE&address=400+wrong+Street+sacramento+ca
{
    response: "failed",
    reason: "Address not found"
}

GetHPSDesignations

This method allows you to get health profession shortage designations of a latitude and longitude. Remember that this will only work for coordinates that are of California.

Below is an example of this web service URL with some parameters.

http://geo.oshpd.ca.gov/service/gethpsdesignations?key=YOUR_KEY_HERE&latitude=38.5732617&longitude=-121.5047861&calreachdoctype=

Latitude and Longitude provided above are of 400 R Street Sacramento CA

Parameters

key (required)
An api key must be provided to use this service. Contact ITSD's Manraj Singh to obtain a key.
latitude (required)
Latitude of the address that you want to find the shortage designations for.
longitude(required)
Longitude of the address that you want to find the shortage designations for.
calreachdoctype
Given this parameter, the Area of Unmet Need (in_umn) flag may be determined differently. Currently SongBrown program may require this flag to be computed differently for various programs. For Example, An address's Area of Unmet Need flag(in_umn) Registered Nurse Special Program's application doesn't care about any other flags other than Registered Nurse Shortage Area (rnsa).

Json Response

{
	latitude: 38.5732617,
	longitude: -121.5047861,
	HPSDesignations: {
		ExtensionData: { },
		census_tract: "21",
		central_valley: true,
		endowment_communities: false,
		hpsa_dc: false,
		hpsa_dc_date: "",
		hpsa_dc_id: null,
		hpsa_dc_score: 0,
		hpsa_mh: false,
		hpsa_mh_date: "",
		hpsa_mh_id: null,
		hpsa_mh_score: 0,
		hpsa_pc: true,
		hpsa_pc_date: "8/18/2011 12:00:00 AM",
		hpsa_pc_id: "10699906PK",
		hpsa_pc_score: 14,
		in_umn: true,
		mssa_definition: "Urban",
		mssa_id: "139j",
		mua: false,
		mup: false,
		pcsa: true,
		rnsa: true
	},
	response: "success"
}