HIV.gov

HIV/AIDS Service Provider Locator API

The HIV/AIDS Prevention & Service Provider Locator is a first-of-its-kind, location-based search tool that allows you to search for testing services, housing providers, health centers and other service providers near your current location.

What is an API?

API stands for application programming interface, and is a way for data to be shared in a flexible and open way. This allows for many different uses of the data, by many different groups and individuals.

What data is available through this API?

All of the same location data that you can find through the Locator tool: service provider names, addresses, phone numbers, locations, and so on, categorized by service type.

How do I access the API?

Through https://locator.hiv.gov/data. The following parameters are available:

lat & long

Perform a search using latitude and longitude coordinates. Lat and long are rounded to 3 decimal places for consistency in search results. If lat, long and zip are provided, lat and long will be ignored.

services

A comma separated list of the types of services to search. The following are the currently available service types:

  1. testing
  2. housing
  3. clinics
  4. ryanwhite
  5. mentalhealth
  6. substanceabuse
  7. familyplanning

distance

Search by distance in miles from the provided location. Accepts values between 1 and 50 in increments of 5. Invalid values will be clamped to the nearest multiple of 5. If no distance is provided, defaults to 1 mile.

format

Determines the format of the returned data. Currently available formats are:

  1. json (default)
  2. html

callback

If a callback parameter is included, the response will be sent using JSON-P.

What will the data I get back look like?

If you don’t request a different format, the data in the response will be in JSON format. Here’s a quick example:

Could I see some examples?

Sure, here are a few example requests:

https://locator.hiv.gov/data?lat=36.180774&long=-86.735863

https://locator.hiv.gov/data?lat=36.180774&long=-86.735863&distance=10

https://locator.hiv.gov/data?lat=36.180774&long=-86.735863&format=html

https://locator.hiv.gov/data?lat=36.180774&long=-86.735863&format=xml&distance=30