Introduction
Welcome to the Homeyou website API documentation.
This documentation provides comprehensive information about the Homeyou website API endpoints.
States
This is the states data retrieve service.
List
To get the states list data:
<?php
$url = "https://api-costs.homeyou.com/state/list?token=TOKEN";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
[
{
"abbreviation_state": "AK",
"nm_state": "Alaska",
"url_state": "alaska"
},
{
"abbreviation_state": "AL",
"nm_state": "Alabama",
"url_state": "alabama"
},
{
"abbreviation_state": "AR",
"nm_state": "Arkansas",
"url_state": "arkansas"
}
...
]
Retrieve information about the currently authenticated user.
HTTP Request
GET /state/list?token=TOKEN
Token url query param
| Parameter | Description |
|---|---|
| token | API token |
Auth
Authentication endpoints. Login returns a Hashids-encoded user id that must be passed in subsequent authenticated requests (reviews, etc.). No sessions are used — the id is the stateless user identifier.
Login
To authenticate a user:
<?php
$url = "https://api-costs.homeyou.com/auth/login";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN',
'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'email' => 'user@example.com',
'password' => 'secret',
]));
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response (success):
{
"success": true,
"id": "Mj3K9pXzQw",
"first_name": "John",
"last_name": "Doe",
"email": "user@example.com",
"avatar_url": "https://www.homeyou.com/images/img-no-picture-profile.png"
}
Example response (error):
{
"success": false,
"error": "Invalid email or password"
}
HTTP Request
POST /auth/login
Body params
| Parameter | Required | Description |
|---|---|---|
| Yes | User email | |
| password | Yes | User password |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
| Content-Type | application/json |
Notes
The id field returned is a Hashids-encoded user identifier. Store it client-side and pass it in subsequent authenticated requests (e.g., submitting a review).
Sign
Endpoints for token-based authentication flows.
By Token
To authenticate a user via temporary token (without project):
<?php
$url = "https://api-costs.homeyou.com/sign/by-token/TOKEN";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"id": "Ab3dEf7gHi",
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com",
"avatar_url": "https://homeyou.s3.amazonaws.com/...",
"project": {
"id": "abc123xyz",
"id_lead": 456,
"cd_category": 3,
"nm_category": "Painting",
"zipcode_lead": "10001"
},
"funnel": "painting-upsell"
}
Response when no funnel is available:
{
"id": "Ab3dEf7gHi",
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com",
"avatar_url": "https://homeyou.s3.amazonaws.com/...",
"project": {
"id": "abc123xyz",
"id_lead": 456,
"cd_category": 3,
"nm_category": "Painting",
"zipcode_lead": "10001"
},
"funnel": null
}
Authenticates a user via a temporary token (psw_code_user), loads their projects from WiserLeads, and returns the same fields as auth/login plus the selected project and upsell funnel. The frontend should store id as Bearer token (same as login) and navigate to the project detail page with action=thank-you, appending #funnel if present.
Returns 404 if the token is invalid or no project is found.
HTTP Request
GET /sign/by-token/<tmp_password>
GET /sign/by-token/<tmp_password>/<project>
Path params
| Parameter | Required | Description |
|---|---|---|
| tmp_password | yes | Temporary user token (psw_code_user) |
| project | no | Lead ID to select a specific project. Uses first if omitted. |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Password
Endpoints for password recovery and reset flows.
Forgot Password
To request a password reset email:
<?php
$url = "https://api-costs.homeyou.com/password/forgot";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN',
'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'email' => 'user@example.com',
]));
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
Success response:
{ "success": true }
Error responses:
{ "success": false, "status": "invalid" }
{ "success": false, "status": "not-found" }
{ "success": false, "status": "inactive" }
Sends a password recovery email with a reset link to the user. The email contains the psw_code_user token used in GET /password/reset/<token>.
HTTP Request
POST /password/forgot
Body params
| Parameter | Required | Description |
|---|---|---|
| yes | User email |
Status values
| Status | Meaning |
|---|---|
| invalid | Email format is invalid |
| not-found | No account found for this email |
| inactive | Account exists but is inactive |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Reset Password
To reset the password:
<?php
$url = "https://api-costs.homeyou.com/password/reset";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN',
'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'token' => 'RESET_TOKEN',
'password' => 'newpassword',
]));
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
Success response (same fields as
auth/login):
{
"id": "Ab3dEf7gHi",
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com",
"avatar_url": "https://homeyou.s3.amazonaws.com/..."
}
Error responses:
{ "success": false, "status": "invalid" }
{ "success": false, "status": "invalid-token" }
Validates the token, updates the password, invalidates the old token (generates a new psw_code_user), and returns auth data. The frontend should store id as Bearer token (same as auth/login) and redirect the user.
HTTP Request
POST /password/reset
Body params
| Parameter | Required | Description |
|---|---|---|
| token | yes | Reset token (psw_code_user) |
| password | yes | New password (min 6 characters) |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Homeowner
Endpoints for authenticated homeowner flows. All endpoints require a user_token (Hashids-encoded user ID returned by auth/login or sign/by-token).
Estimates
Index
To get the estimates page data:
<?php
$url = "https://api-costs.homeyou.com/homeowner/estimates";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN',
'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'user_token' => 'USER_TOKEN',
'id' => 'a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1',
'category' => 3,
'service' => 101,
]));
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"category": {
"cd_category": 3,
"nm_category": "Painting",
"url_slug_category": "painting"
},
"category_lowercase": "painting",
"lead_hash": "a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1",
"id_service": 101,
"project": { }
}
HTTP Request
POST /homeowner/estimates
Body params
| Parameter | Required | Description |
|---|---|---|
| user_token | yes | User Hashids token (from auth/login) |
| id | yes | Project hash (SHA256, 64 chars) |
| category | yes | Category ID (cd_category) |
| service | no | Service ID (defaults to 0) |
Submit
To submit an estimate (upsell):
<?php
$url = "https://api-costs.homeyou.com/homeowner/estimates/submit";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN',
'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'user_token' => 'USER_TOKEN',
'lead_hash' => 'abc123xyz',
'category' => 3,
'service' => 101,
'location' => '10001',
'text' => 'Need interior painting done',
'utm_source' => 'email',
'utm_campaign' => 'homeyou-newsletter-2024-01',
]));
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
Success response:
{
"success": true,
"id": "newLeadHashXyz"
}
Error response (missing category):
{ "success": false }
Submits an upsell lead to WiserLeads. The frontend should redirect to /homeowner/project/detail?id={id}&action=thank-you after success.
HTTP Request
POST /homeowner/estimates/submit
Body params
| Parameter | Required | Description |
|---|---|---|
| user_token | yes | User Hashids token (from auth/login) |
| lead_hash | yes | Project hash |
| category | yes | Category ID (cd_category) |
| service | no | Service ID |
| location | no | Zipcode/location |
| text | no | Project description |
| utm_source | no | UTM tracking |
| utm_medium | no | UTM tracking |
| utm_term | no | UTM tracking |
| utm_content | no | UTM tracking |
| utm_campaign | no | UTM tracking |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Costs
This is the costs data retrieve service. The endpoints in this area allow us to retrieve information about all costs pages data.
Index
To get the costs index page data:
<?php
$url = "https://api-costs.homeyou.com/costs";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"seoTitle": "2025 Home Improvement Service Cost Guides | homeyou",
"seoDescription": "The homeyou Cost Guides help you estimate the cost of home improvement projects in your city. Get accurate estimates home repair and remodeling projects.",
"topServices": [
{
"title": "Painting",
"imageUrl": "https://www.homeyou.com/images/directory/popular/painting.jpg",
"url": "https://www.homeyou.com/costs/painting",
"slug": "painting"
},
{
"title": "Landscaping",
"imageUrl": "https://www.homeyou.com/images/directory/popular/landscaping.jpg",
"url": "https://www.homeyou.com/costs/landscaping",
"slug": "landscaping"
}
...
],
"services": {
"Additions and Remodels": {
"title": "Additions and Remodels",
"url": "https://www.homeyou.com/additions-and-remodels-cost",
"slug": "additions-and-remodels",
"services": [
{
"title": "Basement Remodeling",
"url": "https://www.homeyou.com/costs/basement-remodeling",
"slug": "basement-remodeling"
},
{
"title": "Custom Garages",
"url": "https://www.homeyou.com/costs/custom-garages",
"slug": "custom-garages"
},
{
"title": "Garage Remodeling",
"url": "https://www.homeyou.com/costs/garage-remodeling",
"slug": "garage-remodeling"
}
...
]
},
"Appliances": {
"title": "Appliances",
"url": "https://www.homeyou.com/appliances-cost",
"slug": "appliances",
"services": [
{
"title": "Appliance Repair",
"url": "https://www.homeyou.com/costs/appliance-repair",
"slug": "appliance-repair"
},
{
"title": "Commercial Refrigeration Repair",
"url": "https://www.homeyou.com/costs/commercial-refrigeration-repair",
"slug": "commercial-refrigeration-repair"
},
{
"title": "Dryer Repair",
"url": "https://www.homeyou.com/costs/dryer-repair",
"slug": "dryer-repair"
},
{
"title": "Oven Repair",
"url": "https://www.homeyou.com/costs/oven-repair",
"slug": "oven-repair"
},
{
"title": "Refrigerator Repair",
"url": "https://www.homeyou.com/costs/refrigerator-repair",
"slug": "refrigerator-repair"
}
...
]
}
...
},
"servicesList": [
{
"id": "",
"title": "HVAC",
"children": [
{
"id": "%7B%22category%22%3A%228%22%2C%22service%22%3A%22234%22%7D",
"title": "AC Companies"
},
{
"id": "%7B%22category%22%3A%228%22%2C%22service%22%3A%22233%22%7D",
"title": "AC Installation"
},
...
]
},
{
"id": "",
"title": "Siding",
"children": [
{
"id": "%7B%22category%22%3A%2221%22%2C%22service%22%3A%22337%22%7D",
"title": "Aluminum Siding Repair"
},
{
"id": "%7B%22category%22%3A%2221%22%2C%22service%22%3A%22354%22%7D",
"title": "Fiber Cement Siding"
},
...
]
}
...
]
}
HTTP Request
GET /costs
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
States By Service
To get the costs states by service page data:
<?php
$url = "https://api-costs.homeyou.com/costs/states-by-service/<service_slug>";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"title": "AC Companies",
"states": [
{
"title": "Alaska",
"url": "https://www.homeyou.com/costs/ac-companies/ak",
"prefix_state": "AK"
},
{
"title": "Alabama",
"url": "https://www.homeyou.com/costs/ac-companies/al",
"prefix_state": "AL"
},
{
"title": "Arkansas",
"url": "https://www.homeyou.com/costs/ac-companies/ar",
"prefix_state": "AR"
},
{
"title": "Arizona",
"url": "https://www.homeyou.com/costs/ac-companies/az",
"prefix_state": "AZ"
}
...
],
"seoTitle": "2025 AC Companies Cost | How Much to hire an AC company - homeyou",
"seoDescription": "The homeyou AC Companies cost guides help you estimate the cost to hire an AC company in your city. Get accurate estimates on AC Companies, as reported by homeyou customers."
}
HTTP Request
GET /costs/states-by-service/<service_slug>
Path params
| Parameter | Description |
|---|---|
| service_slug | Service Slug |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Cities by State and Service
To get the costs cities by state and service page data:
<?php
$url = "https://api-costs.homeyou.com/costs/cities-by-state-and-service/<state_prefix>/<service_slug>";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"seoTitle": "2025 Alaska AC Companies Costs | How Much to hire an AC company - homeyou",
"seoDescription": "The homeyou Alaska AC Companies cost guides help you estimate the cost to hire an AC company in Alaska. Get accurate estimates on AC Companies, as reported by homeyou customers.",
"title": "2025 Alaska AC Companies Cost Guides",
"serviceName": "AC Companies",
"topCities": [
{
"title": "Anchorage",
"url": "https://www.homeyou.com/ak/ac-companies-anchorage-costs",
"slug": "ak-ac-companies-anchorage-costs"
},
{
"title": "Fairbanks",
"url": "https://www.homeyou.com/ak/ac-companies-fairbanks-costs",
"slug": "ak-ac-companies-fairbanks-costs"
},
{
"title": "Juneau",
"url": "https://www.homeyou.com/ak/ac-companies-juneau-costs",
"slug": "ak-ac-companies-juneau-costs"
}
...
],
"additionalCities": [
{
"title": "Eielson Afb",
"url": "https://www.homeyou.com/ak/ac-companies-eielson-afb-costs",
"slug": "ak-ac-companies-eielson-afb-costs"
},
{
"title": "Sterling",
"url": "https://www.homeyou.com/ak/ac-companies-sterling-costs",
"slug": "ak-ac-companies-sterling-costs"
},
{
"title": "Kodiak",
"url": "https://www.homeyou.com/ak/ac-companies-kodiak-costs",
"slug": "ak-ac-companies-kodiak-costs"
}
]
}
HTTP Request
GET /costs/cities-by-state-and-service/<state_prefix>/<service_slug>
Headers:
- Authorization: Bearer TOKEN
Path params
| Parameter | Description |
|---|---|
| service_slug | Service Slug |
| state_prefix | State Prefix |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Service Landing Page
To get the costs service landing page data:
<?php
$url = "https://api-costs.homeyou.com/costs/service-landing-page/<service_slug>";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"seoTitle": "AC Companies in Anchorage, AK - Costs 05 / 2025 - homeyou",
"seoDescription": "AC Companies Cost Guide offers cost estimates on AC Companies in Anchorage. Get accurate prices to AC Companies in Anchorage for 2025, as reported by homeyou customers.",
"title": "How Much Does it Cost to Hire an AC Company in Anchorage?",
"category": "8",
"serviceName": "AC Companies",
"serviceSlug": "ac-companies",
"categoryName": "HVAC",
"categorySlug": "hvac",
"cityName": "Anchorage",
"stateCode": "AK",
"zipCode": "99501",
"phoneTitle": "1-844-HOMEYOU",
"phoneNumber": "+12123456789",
"relatedQuestionsTitle": "What type of project is this?",
"firstParagraphText": "<p>First paragraph text.</p>",
"costSnippetsText": "Cost snippet text.",
"costParagraphsText": "Cost paragraph text;",
"chartImage": "https://www.homeyou.com/costs/i/MzA2NzozMzQz/ak-ac-companies-anchorage-costs.png",
"lastUpdated": "Mar 31, 2017",
"bulletText1": "Experienced AC Companies in Anchorage, AK",
"bulletText2": "Residential & Commercial Service",
"bulletText3": "Same Day Consultations Available in Alaska",
"quotesUrl": "https://quotes.homeyou.com/?funnel=13&buttons=btn-primary&phone=1-844-HOMEYOU&step1_title=",
"signupUrl": "https://signup.homeyou.com",
"attributes": [
{
"title": "Central AC",
"value": "%7B%22category%22%3A%228%22%2C%22service_code%22%3A%22HVAC_CENTRAL_AC%22%7D"
},
...
],
"definitionDate": "06/27/2017",
"customPriceCalculatorUrl": "https://www.homeyou.com/costs/c/ak-ac-companies-anchorage-costs",
"datasource": {
"avgrangemincost": 1000,
"avgrangemaxcost": 1000,
"mincost": 1000,
"avgcost": 1000,
"maxcost": 1000,
"s1": "$1,000.00",
"s2": "$1,000.00",
"s3": "$1,000.00",
"s4": "$1,000.00",
"has_full_costs": true,
"has_return_amount": true,
"return_amount": "1,000",
"type-costs": {
"Materials": "1,000",
...
},
"items": [
{
"title": "Air Conditioning Unit Cost",
"description": "Non-discounted retail cost for common, mid-grade air conditioning unit.",
"quantity": "1 Unit",
"low": 1000.0,
"high": 1000.0,
"avg": 1000.0
}
...
],
"unit_cost": 1000.0,
"unit_cost_low": 1000.0,
"unit_cost_high": 1000.0,
"total_cost": 1000.0,
"total_cost_low": 1000.0,
"total_cost_high": 1000.0,
"uv_singular": "Unit",
"uv": "units",
"quantity": "1 Unit",
"name_verb": "Install Air Conditioning",
"local_cost": "1,000",
"national_cost": "1,000",
"low_labor": 1000.0,
"high_labor": 1000.0
},
"bannerJobDone": [
{
"title": "When do you need the job done?",
"url": "https://quotes.homeyou.com/?funnel=13&buttons=btn-primary&phone=1-844-HOMEYOU&step1_title=&attributes=%7B%22request_completed%22%3A%22Timing+is+Flexible%22%7D"
}
...
],
"costsWidget": [
{
"title": "Materials",
"cost": "1,000"
}
...
],
"faqWidget": [
{
"question": "FAQ Question?",
"answer": "FAQ Answer."
}
...
],
"relatedServicesWidget": [
{
"title": "Heating Repair",
"url": "https://www.homeyou.com/ak/heating-repair-anchorage-costs",
"slug": "ak-heating-repair-anchorage-costs"
}
...
],
"leadsWidget": [
{
"title": "Central AC",
"name": "Graham B.",
"city": "Anchorage, AK",
"description": "Description"
}
...
],
"topCitiesWidget": {
"title": "AC Companies in Alaska",
"topCities": [
{
"title": "Fairbanks",
"url": "https://www.homeyou.com/ak/ac-companies-fairbanks-costs",
"state_code": "AK",
"slug": "ak-ac-companies-fairbanks-costs"
}
...
]
},
"zipCodesWeServiceWidget": [
{
"label": "99623",
"slug": "ak-ac-companies-wasilla-costs"
}
],
"contractorsWidget": [
{
"id_business": CompanyId,
"nm_company": "Company Name",
"address_company": "Company Address",
"city_company": "Company City",
"state_company": "Company State Prefix (AK..;)",
"zip_code_company": "Company Zipcode",
"phone_company": "Company Phone",
"rating": 57,
"lat": 60.0,
"lon": -150.0,
"claimed": false,
"slug": "",
"logo": "contractors/7333/4641-juneau-st-ak-anchorage-99503.jpg",
"is_open": true,
"hours_company": {
"Sun": "Closed",
"Mon": "8:00 am - 6:00 pm",
"Tue": "8:00 am - 6:00 pm",
"Wed": "8:00 am - 6:00 pm",
"Thu": "8:00 am - 6:00 pm",
"Fri": "8:00 am - 6:00 pm",
"Sat": "Closed"
},
"license": [],
"categories": [
{
"cd_category": "1",
"nm_category": "Plumbing"
}
...
]
}
...
],
"chartUrlMobile": "https://www.homeyou.com/costs/cim/c8nr1u/ak-hardwood-flooring-refinishing-anchorage-costs.png",
"chartUrlDesktop": "https://www.homeyou.com/costs/ci/c8nr1u/ak-hardwood-flooring-refinishing-anchorage-costs-lg.png"
}
HTTP Request
GET /costs/service-landing-page/<service_slug>
Path params
| Parameter | Description |
|---|---|
| service_slug | Service Slug |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Category Landing Page
To get the costs category landing page data:
<?php
$url = "https://api-costs.homeyou.com/costs/category-landing-page/<category_or_service_slug>";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"isService": true,
"writer": {
"name": "John Doe",
"image": "https://www.homeyou.com/images/writer.jpg",
"slug": "john-doe"
},
"reviewer": {
"name": "Jane Doe",
"image": "https://www.homeyou.com/images/reviewer.jpg",
"slug": "jane-doe"
},
"seoTitle": "True Cost to Build a Garage in 2025 | homeyou",
"seoDescription": "Use homeyou's guide to understand the cost to build a garage in 2025, details on pricing, factors affecting costs, and tips for hiring the right contractor.",
"sourceId": 699,
"sourceName": "Garage Building",
"sourceSlug": "garage-building",
"categoryId": 8,
"categorySlug": "hvac",
"categoryName": "HVAC",
"h1": "What Is the Average Cost of Garage Building?",
"excerpt": "The price to build a garage in 2025 can range from **$9,781** to **$72,818**, with an average of **$29,473**.",
"phoneTitle": "1-844-HOMEYOU",
"phoneNumber": "+18444663968",
"costGuideContent": "<p>Cost guide content</p>",
"costGuideContentPublished": 1762922337,
"costGuideContentUpdated": 1763042846,
"readMoreArticles": [
{
"title": "6 Reasons Why You Should Hire a Landscaping Contractor",
"url": "https://www.homeyou.com/hire-landscaping-contractor",
"imageUrl": "http://images.homeyou.com/website/website/base/59e/9a8/f5a/cover-landscape-contractor.jpg"
},
...
],
"services": [
{
"title": "AC Companies",
"slug": "ac-companies",
"attributes": "%7B%22category%22%3A%228%22%2C%22service_code%22%3A%22HVAC_CENTRAL_AC%22%7D"
},
{
"title": "AC Installation",
"slug": "ac-installation",
"attributes": "%7B%22category%22%3A%228%22%2C%22service_code%22%3A%22HVAC_CENTRAL_AC%22%7D"
}
...
],
"industryCategory": "HVAC",
"relatedServices": [
{
"title": "AC Repair",
"slug": "ac-repair",
"fakeProjectQuantity": 24853,
"avgCost": "385"
},
{
"title": "Air Conditioning Repair",
"slug": "air-conditioning-repair",
"fakeProjectQuantity": 20721,
"avgCost": "365"
}
],
"featuredProsWidget": {
"categoryName": "HVAC",
"pros": [
{
"title": "WC Heating & Air Conditioning Inc.",
"url": "https://www.homeyou.com/wc-heating-air-conditioning-inc-murrieta-ca",
"imageUrl": "https://www.homeyou.com/@web/images/directory/business.png",
"city": "Murrieta",
"state": "CA"
},
{
"title": "RCF Service, LLC",
"url": "https://www.homeyou.com/rcf-service-llc-farmington-nm-5054070466",
"imageUrl": "https://www.homeyou.com/@web/images/directory/business.png",
"city": "Farmington",
"state": "NM"
},
{
"title": "Mojo Mechanical Heating & Cooling",
"url": "https://www.homeyou.com/mojo-mechanical-heating-cooling-tucson-az",
"imageUrl": "https://www.homeyou.com/@web/images/directory/business.png",
"city": "Tucson",
"state": "AZ"
}
]
},
"topCitiesDirectory": [
{
"nmCity": "Ontario",
"nmCategory": "HVAC",
"title": "Ontario, CA",
"categorySlug": "hvac",
"stateSlug": "california",
"citySlug": "ontario"
},
{
"nmCity": "Pasadena",
"nmCategory": "HVAC",
"title": "Pasadena, CA",
"categorySlug": "hvac",
"stateSlug": "california",
"citySlug": "pasadena"
},
...
],
"statesWeCover": [
{
"title": "Alabama",
"slug": "alabama",
"categoryName": "HVAC"
},
{
"title": "Alaska",
"slug": "alaska",
"categoryName": "HVAC"
}
...
],
"topCitiesRatings": [
{
"title": "Atlanta, GA",
"slugCity": "atlanta",
"slugState": "GA"
},
{
"title": "Boise, ID",
"slugCity": "boise",
"slugState": "ID"
}
...
],
"servicesNotFromCategory": [
{
"url": "https://www.homeyou.com/ak/plumbing-anchorage-costs",
"title": "Plumbing",
"slug": "ak-plumbing-anchorage-costs"
},
{
"url": "https://www.homeyou.com/ak/house-painting-anchorage-costs",
"title": "House Painting",
"slug": "ak-house-painting-anchorage-costs"
}
...
],
"averageCosts": {
"min": 1000.00,
"average": 1500.00,
"max": 2000.00,
"unit": "Unit"
},
"relatedServicesCost": [
{
"nm_service": "Finish Basement",
"slug": "finish-basement-cost"
},
{
"nm_service": "Garage Conversion",
"slug": "garage-conversion-cost"
},
{
"nm_service": "Garage Remodel",
"slug": "garage-remodel-cost"
},
{
"nm_service": "Garage Addition",
"slug": "garage-addition-cost"
},
...
],
"categoriesList": {
"Additions and Remodels": {
"title": "Additions and Remodels",
"url": "https://www.homeyou.com/additions-and-remodels-cost",
"slug": "additions-and-remodels",
},
...
],
"faq": [
{
"question": "What is the average cost of garage building?",
"answer": "The price to build a garage in 2025 can range from **$9,781** to **$72,818**, with an average of **$29,473**."
},
...
]
}
HTTP Request
GET /costs/category-landing-page/<category_or_service_slug>
Headers:
- Authorization: Bearer TOKEN
Path params
| Parameter | Description |
|---|---|
| category_or_service_slug | Category or Service Slug |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Cost Guide URL
To get the costs cost guide url:
<?php
$url = "https://api-costs.homeyou.com/costs/cost-guide-url/<zipcode>/<service>";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"success": true,
"url": "https://www.homeyou.com/ak/concrete-anchorage-costs"
}
HTTP Request
GET /costs/cost-guide-url/<zipcode>/<service>
Headers:
- Authorization: Bearer TOKEN
Path params
| Parameter | Description |
|---|---|
| zipcode | Zip Code |
| service | Id Wl Service |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Costs Calculator
To get the costs calculator page data:
<?php
$url = "https://api-costs.homeyou.com/costs/calculator/<slug>/<value>";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"avgrangemincost": 1000.0,
"avgrangemaxcost": 1000,
"mincost": 1000,
"avgcost": 1000,
"maxcost": 1000,
"s1": "$1,000.00",
"s2": "$1,000.00",
"s3": "$1,000.00",
"s4": "$1,000.00",
"has_full_costs": true,
"has_return_amount": true,
"return_amount": "1,000",
"type-costs": {
"Materials": "1,000",
"Labor": "1,000",
"Supplies": "1,000",
"Equipment": "1,000"
},
"items": [
{
"title": "Air Conditioning Unit Cost",
"description": "Non-discounted retail cost for common, mid-grade air conditioning unit.",
"quantity": "3 Units",
"low": 6326.898032,
"high": 8560.454448,
"avg": 7443.676240000001
},
{
"title": "Air Conditioning Unit Labor",
"description": "Direct labor expenses to install air conditioning.",
"quantity": "18.9 Hours",
"low": 1326.855712,
"high": 1437.041424,
"avg": 1381.948568
}
...
],
"unit_cost": 1000.00,
"unit_cost_low": 1000.00,
"unit_cost_high": 1000.00,
"total_cost": 1000.00,
"total_cost_low": 1000.00,
"total_cost_high": 1000.00,
"uv_singular": "Unit",
"uv": "units",
"quantity": "3 Units",
"name_verb": "Install Air Conditioning",
"local_cost": "1,000",
"national_cost": "1,000",
"low_labor": 1000.00,
"high_labor": 1000.00,
"seoTitle": "What is the price for AC Companies in Anchorage, AK?"
}
HTTP Request
GET /costs/calculator/<slug>/<value>
Headers:
- Authorization: Bearer TOKEN
Path params
| Parameter | Description |
|---|---|
| slug | Service Slug |
| value | Units Quantity |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Chart Small
To generate a cost widget chart image:
<?php
// Build the param: base64("min:avg:max") with padding stripped
$param = trim(base64_encode("500:1000:2000"), '=');
$slug = "basement-remodeling";
$url = "https://api-costs.homeyou.com/chart/small/{$param}/{$slug}";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"image": "data:image/png;base64,iVBORw0KGgo..."
}
HTTP Request
GET /chart/small/<param>/<slug>
Path params
| Parameter | Description |
|---|---|
| param | Base64-encoded string of min:avg:max cost values with padding = removed |
| slug | Service slug (e.g., basement-remodeling) |
Building the param
$param = trim(base64_encode("{$min}:{$avg}:{$max}"), '=');
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Inspiration
The inspiration section covers articles, pictures (gallery), author pages and search. All list endpoints support pagination via the p query param (0-based). Articles and pictures are returned as separate arrays — the frontend decides how to interleave them.
List
To get the inspiration list:
<?php
$url = "https://api-costs.homeyou.com/inspiration?p=0";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer TOKEN']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"seoTitle": "Articles, Pictures, Ideas | Inspiration | homeyou",
"items": [
{
"type": "article",
"size": "one-quarter",
"data": {
"title": "10 Tips for a Perfect Kitchen Remodel",
"slug": "10-tips-perfect-kitchen-remodel",
"excerpt": "Planning a kitchen remodel? Here are 10 tips...",
"imageUrl": "https://homeyou.s3.amazonaws.com/media/Kitchen/kitchen1.jpg",
"date": "March 15, 2024",
"heatLevel": "12,453",
"authorName": "Jane Doe",
"authorSlug": "jane-doe",
"categorySlug": "kitchen",
"categoryName": "Kitchen"
}
},
{
"type": "article",
"size": "one-quarter",
"data": { ... }
},
{
"type": "article",
"size": "one-quarter",
"data": { ... }
},
{
"type": "picture",
"size": "one-quarter",
"data": {
"title": "Modern Kitchen Design",
"description": "Open-concept kitchen with island.",
"imageUrl": "https://homeyou.s3.amazonaws.com/pictures/kitchen-modern.jpg",
"thumbUrl": "https://homeyou.s3.amazonaws.com/pictures/thumbs/kitchen-modern.jpg"
}
}
...
],
"nextPage": 1
}
Items follow the same interleaved pattern as the frontend: 3 articles + 1 picture repeating. The size field indicates the grid column width (one-quarter, one-third, two-third) for the frontend to build the layout.
HTTP Request
GET /inspiration
Query params
| Parameter | Required | Description |
|---|---|---|
| p | No | Page number, 0-based (default 0) |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Category
To get articles and pictures for a category:
<?php
$url = "https://api-costs.homeyou.com/inspiration/category/<slug>?p=0";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer TOKEN']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"seoTitle": "Kitchen Inspiration - homeyou",
"category": {
"name": "Kitchen",
"slug": "kitchen"
},
"items": [
{
"type": "picture",
"size": "two-third",
"data": {
"title": "Modern Kitchen Design",
"description": "Open-concept kitchen with island.",
"imageUrl": "https://homeyou.s3.amazonaws.com/pictures/kitchen-modern.jpg",
"thumbUrl": "https://homeyou.s3.amazonaws.com/pictures/thumbs/kitchen-modern.jpg"
}
},
{
"type": "article",
"size": "one-third",
"data": { ... }
}
...
],
"nextPage": 1
}
When pictures are available the layout alternates between two-third pictures and one-third articles. When there are no pictures, only articles are returned with one-third size each.
HTTP Request
GET /inspiration/category/<slug>
Path params
| Parameter | Description |
|---|---|
| slug | Category slug |
Query params
| Parameter | Required | Description |
|---|---|---|
| p | No | Page number, 0-based (default 0) |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Article Detail
To get a single article:
<?php
$url = "https://api-costs.homeyou.com/inspiration/article/<slug>";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer TOKEN']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"seoTitle": "10 Tips for a Perfect Kitchen Remodel - homeyou",
"seoDescription": "Planning a kitchen remodel? Here are 10 tips...",
"article": {
"title": "10 Tips for a Perfect Kitchen Remodel",
"slug": "10-tips-perfect-kitchen-remodel",
"excerpt": "Planning a kitchen remodel? Here are 10 tips...",
"body": "<p>Full HTML content of the article...</p>",
"imageUrl": "https://homeyou.s3.amazonaws.com/media/Kitchen/kitchen1.jpg",
"socialMediaImage": "https://homeyou.s3.amazonaws.com/media/Kitchen/kitchen1-lg.jpg",
"date": "March 15, 2024",
"updatedAt": 1710460800,
"heatLevel": "12,453",
"authorName": "Jane Doe",
"authorSlug": "jane-doe",
"authorImageUrl": "https://homeyou.s3.amazonaws.com/authors/jane-doe.jpg",
"locationAuthor": "Senior Editor",
"categories": [
{ "name": "Kitchen", "slug": "kitchen" }
],
"tags": ["remodel", "kitchen", "design"]
}
}
HTTP Request
GET /inspiration/article/<slug>
Path params
| Parameter | Description |
|---|---|
| slug | Article slug |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Search
To search articles and pictures:
<?php
$url = "https://api-costs.homeyou.com/inspiration/search?s=kitchen&p=0";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer TOKEN']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"seoTitle": "Inspiration Search - homeyou",
"searchQuery": "kitchen",
"noResults": false,
"items": [
{
"type": "article",
"size": "one-quarter",
"data": {
"title": "10 Tips for a Perfect Kitchen Remodel",
"slug": "10-tips-perfect-kitchen-remodel",
"excerpt": "Planning a kitchen remodel?",
"imageUrl": "https://homeyou.s3.amazonaws.com/media/Kitchen/kitchen1.jpg",
"date": "March 15, 2024",
"heatLevel": "12,453",
"authorName": "Jane Doe",
"authorSlug": "jane-doe",
"categorySlug": "kitchen",
"categoryName": "Kitchen"
}
}
...
],
"nextPage": 1
}
When noResults is true, recent articles/pictures are returned as fallback. Items follow the same 3 articles + 1 picture pattern as the list page.
HTTP Request
GET /inspiration/search
Query params
| Parameter | Required | Description |
|---|---|---|
| s | Yes | Search query (min 4 characters) |
| p | No | Page number, 0-based (default 0) |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Authors
To get the full authors list:
<?php
$url = "https://api-costs.homeyou.com/inspiration/authors";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer TOKEN']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"seoTitle": "Meet our Writers | Articles - homeyou",
"editors": [
{
"slug": "jane-doe",
"name": "Jane Doe",
"location": "Senior Editor",
"avatarUrl": "https://homeyou.s3.amazonaws.com/authors/jane-doe.jpg",
"blogUrl": null,
"blogName": null,
"socialLinks": [
{ "label": "Twitter", "name": "twitter", "url": "https://twitter.com/janedoe" }
]
}
...
],
"writers": [ ... ],
"bloggers": [ ... ]
}
HTTP Request
GET /inspiration/authors
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Author Detail
To get an author's profile and articles:
<?php
$url = "https://api-costs.homeyou.com/inspiration/author/<slug>?p=0";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer TOKEN']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"seoTitle": "Jane Doe - Author - homeyou",
"author": {
"slug": "jane-doe",
"name": "Jane Doe",
"location": "Senior Editor",
"avatarUrl": "https://homeyou.s3.amazonaws.com/authors/jane-doe.jpg",
"blogUrl": null,
"blogName": null,
"socialLinks": [
{ "label": "Twitter", "name": "twitter", "url": "https://twitter.com/janedoe" }
]
},
"recentPosts": [
{
"title": "10 Tips for a Perfect Kitchen Remodel",
"slug": "10-tips-perfect-kitchen-remodel",
"excerpt": "Planning a kitchen remodel?",
"imageUrl": "https://homeyou.s3.amazonaws.com/media/Kitchen/kitchen1.jpg",
"date": "March 15, 2024",
"heatLevel": "12,453",
"authorName": "Jane Doe",
"authorSlug": "jane-doe",
"categorySlug": "kitchen",
"categoryName": "Kitchen"
}
...
],
"articles": [ ... ],
"pagination": {
"page": 0,
"pageCount": 3,
"hasNext": true
}
}
HTTP Request
GET /inspiration/author/<slug>
Path params
| Parameter | Description |
|---|---|
| slug | Author slug |
Query params
| Parameter | Required | Description |
|---|---|---|
| p | No | Page number, 0-based (default 0) |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Directory
This is the directory data retrieve service. The endpoints in this area allow us to retrieve information about all directory pages data.
Index
To get the directory index page data:
<?php
$url = "https://api-costs.homeyou.com/directory";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"seoTitle": "homeyou | Get Qualified Help from Nearby Home Improvement Professionals",
"seoDescription": "",
"topCategories": [
{
"title": "Painting",
"url_slug_category": "painting",
"image_url": "https://www.homeyou.com/images/directory/popular/painting.jpg"
},
{
"title": "Landscaping",
"url_slug_category": "landscaping",
"image_url": "https://www.homeyou.com/images/directory/popular/landscaping.jpg"
},
...
],
"moreCategories": [
{
"title": "Additions and Remodels",
"url_slug_category": "additions-and-remodels"
},
{
"title": "Appliances",
"url_slug_category": "appliances"
},
...
],
"featuredArticles": {
"topTrendingRows": [
{
"title": "Our Guide to 2015's Hottest Interior Designs",
"url": "https://www.homeyou.com/guide-to-2015-interior-designs",
"imageUrl": "https://homeyou.s3.amazonaws.com/media/Interior Design/design3.jpg",
"heatLevel": "7,731",
"categoryLinks": {
"Landscape": "https://www.homeyou.com/inspiration/landscape"
}
},
{
"title": "The Secret to Kitchen Design",
"url": "https://www.homeyou.com/the-secret-to-kitchen-design",
"imageUrl": "https://homeyou.s3.amazonaws.com/media/Kitchen/kitchen-triangle3.jpg",
"heatLevel": "870,977",
"categoryLinks": {
"Landscape": "https://www.homeyou.com/inspiration/landscape"
}
}
...
],
"landscapeRows": [
{
"title": "Our Guide to 2015's Hottest Interior Designs",
"url": "https://www.homeyou.com/guide-to-2015-interior-designs",
"imageUrl": "https://homeyou.s3.amazonaws.com/media/Interior Design/design3.jpg",
"heatLevel": "7,731",
"categoryLinks": {
"Landscape": "https://www.homeyou.com/inspiration/landscape"
}
},
{
"title": "The Secret to Kitchen Design",
"url": "https://www.homeyou.com/the-secret-to-kitchen-design",
"imageUrl": "https://homeyou.s3.amazonaws.com/media/Kitchen/kitchen-triangle3.jpg",
"heatLevel": "870,977",
"categoryLinks": {
"Landscape": "https://www.homeyou.com/inspiration/landscape"
}
}
...
],
"homeImprovementRows": [
{
"title": "Our Guide to 2015's Hottest Interior Designs",
"url": "https://www.homeyou.com/guide-to-2015-interior-designs",
"imageUrl": "https://homeyou.s3.amazonaws.com/media/Interior Design/design3.jpg",
"heatLevel": "7,731",
"categoryLinks": {
"Landscape": "https://www.homeyou.com/inspiration/landscape"
}
},
{
"title": "The Secret to Kitchen Design",
"url": "https://www.homeyou.com/the-secret-to-kitchen-design",
"imageUrl": "https://homeyou.s3.amazonaws.com/media/Kitchen/kitchen-triangle3.jpg",
"heatLevel": "870,977",
"categoryLinks": {
"Landscape": "https://www.homeyou.com/inspiration/landscape"
}
}
...
]
},
"requestedServices": [
{
"nm_service": "Tree Trimming",
"nm_city": "Miami",
"prefix_state": "FL",
"url_slug_category": "tree-service",
"url_state": "florida",
"slug_city": "miami"
},
{
"nm_service": "Vinyl Siding",
"nm_city": "Philadelphia",
"prefix_state": "PA",
"url_slug_category": "siding",
"url_state": "pennsylvania",
"slug_city": "philadelphia"
}
...
],
"servicesList": [
{
"id": "",
"title": "HVAC",
"children": [
{
"id": "%7B%22category%22%3A%228%22%2C%22service%22%3A%22234%22%7D",
"title": "AC Companies"
},
{
"id": "%7B%22category%22%3A%228%22%2C%22service%22%3A%22233%22%7D",
"title": "AC Installation"
},
...
]
},
{
"id": "",
"title": "Siding",
"children": [
{
"id": "%7B%22category%22%3A%2221%22%2C%22service%22%3A%22337%22%7D",
"title": "Aluminum Siding Repair"
},
{
"id": "%7B%22category%22%3A%2221%22%2C%22service%22%3A%22354%22%7D",
"title": "Fiber Cement Siding"
},
...
]
}
...
]
}
HTTP Request
GET /directory
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Category
To get the directory category page data:
<?php
$url = "https://api-costs.homeyou.com/directory/category/<slug>";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"seoTitle": "Painting | Top 100 | homeyou",
"seoDescription": "",
"category": {
"nm_category": "Painting",
"ds_category": "Painters",
"url_slug_category": "painting"
},
"states": [
{
"nm_state": "Alabama",
"url_state": "alabama",
"abbreviation_state": "AL"
},
{
"nm_state": "Alaska",
"url_state": "alaska",
"abbreviation_state": "AK"
}
...
],
"popularCities": [
{
"nm_city": "New York",
"slug_city": "new-york",
"prefix_state": "NY",
"url_state": "new-york",
"url_slug_category": "painting",
"label": "New York, NY Painters"
},
{
"nm_city": "Los Angeles",
"slug_city": "los-angeles",
"prefix_state": "CA",
"url_state": "california",
"url_slug_category": "painting",
"label": "Los Angeles, CA Painters"
}
...
],
"featuredArticles": [
{
"title": "Best Painting Contractors in New York",
"url": "https://www.homeyou.com/best-painting-contractors-in-new-york",
"imageUrl": "https://homeyou.s3.amazonaws.com/media/Painting/painting-ny.jpg"
},
...
]
}
HTTP Request
GET /directory/category/<slug>
Path params
| Parameter | Description |
|---|---|
| slug | Category slug |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
State
To get the directory state page data:
<?php
$url = "https://api-costs.homeyou.com/directory/state/<slug>/<state>";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"seoTitle": "Best Painters in New York - homeyou",
"seoDescription": "Compare best Painters in New York by reviews and prices.",
"category": {
"nm_category": "Painting",
"ds_category": "Painters",
"url_slug_category": "painting"
},
"state": {
"nm_state": "New York",
"url_state": "new-york",
"abbreviation_state": "NY"
},
"topCities": [
{
"nm_city": "New York",
"slug_city": "new-york",
"prefix_state": "NY"
},
{
"nm_city": "Buffalo",
"slug_city": "buffalo",
"prefix_state": "NY"
}
...
],
"cities": [
{
"nm_city": "Albany",
"slug_city": "albany",
"prefix_state": "NY"
},
{
"nm_city": "Rochester",
"slug_city": "rochester",
"prefix_state": "NY"
}
...
],
"featuredArticles": [
{
"title": "Best Painting Contractors in New York",
"url": "https://www.homeyou.com/best-painting-contractors-in-new-york",
"imageUrl": "https://homeyou.s3.amazonaws.com/media/Painting/painting-ny.jpg"
},
...
]
}
HTTP Request
GET /directory/state/<slug>/<state>
Path params
| Parameter | Description |
|---|---|
| slug | Category slug |
| state | State URL slug (e.g., new-york) |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Profiles (City Listing)
To get the directory city profiles listing page data:
<?php
$url = "https://api-costs.homeyou.com/directory/profiles/<slug>/<state>/<city>/<service>";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"seoTitle": "Best Painters in New York, NY - homeyou",
"seoDescription": "Find top-rated Painters in New York, NY. Compare reviews and get free quotes.",
"category": {
"nm_category": "Painting",
"ds_category": "Painters",
"cd_category": "3",
"url_slug_category": "painting"
},
"state": {
"nm_state": "New York",
"url_state": "new-york",
"abbreviation_state": "NY"
},
"city": {
"nm_city": "New York",
"slug_city": "new-york",
"prefix_state": "NY",
"zip_code": "10001"
},
"service": {
"nm_service": "House Painting",
"service_slug": "house-painting"
},
"profiles": [
{
"nm_company": "ABC Painting Co.",
"company_name": "ABC Painting Co.",
"title": "Top Painters in New York, NY",
"slug": "abc-painting-co-new-york-ny",
"city_company": "New York",
"state_company": "NY",
"zip_code_company": "10001",
"address_company": "123 Main St",
"rating_contractor": 85,
"is_licensed": true,
"is_insured": true,
"logo_url": "https://homeyou.s3.amazonaws.com/contractors/123/logo.jpg",
"id_business": 12345,
"is_claimed": true,
"review_stars": "4.50",
"review_start_items": [true, true, true, true, false]
}
...
],
"contractors": [
{
"nm_company": "XYZ Painters LLC",
"slug": "xyz-painters-llc-new-york-ny",
"city_company": "New York",
"state_company": "NY",
"zip_code_company": "10002",
"address_company": "456 Oak Ave",
"rating_contractor": 72,
"is_licensed": false,
"is_insured": true,
"logo_url": null,
"id_business": 67890,
"is_claimed": false,
"review_stars": null,
"review_start_items": [false, false, false, false, false]
}
...
],
"total": 48,
"pagination": {
"page": 0,
"pageCount": 3,
"totalCount": 48,
"pageSize": 20,
"hasNext": true
},
"noResults": false,
"relatedServices": [
{
"nm_service": "House Painting",
"service_slug": "house-painting"
},
{
"nm_service": "Interior Painting",
"service_slug": "interior-painting"
}
...
],
"relatedCategories": [
{
"nm_category": "Flooring",
"url_slug_category": "flooring"
},
{
"nm_category": "HVAC",
"url_slug_category": "hvac"
}
...
],
"recentRequests": [
{
"service_description": "House Painting",
"formatted_name": "John D.",
"location": "New York, NY",
"description": "Need interior painting for 3 rooms."
},
{
"service_description": "Exterior Painting",
"formatted_name": "Sarah M.",
"location": "Brooklyn, NY",
"description": "Full exterior repaint, 2-story house."
}
...
],
"nearCities": [
{
"nm_city": "Brooklyn",
"prefix_state": "NY",
"slug_city": "brooklyn",
"url_state": "new-york"
},
{
"nm_city": "Jersey City",
"prefix_state": "NJ",
"slug_city": "jersey-city",
"url_state": "new-jersey"
}
...
],
"bannerJobDone": [
{
"title": "When do you need the job done?",
"url": "https://quotes.homeyou.com/?step=1&attributes=..."
},
{
"title": "Within 1 week",
"url": "https://quotes.homeyou.com/?step=1&attributes=..."
},
{
"title": "1 - 2 Weeks",
"url": "https://quotes.homeyou.com/?step=1&attributes=..."
},
{
"title": "More than 2 Weeks",
"url": "https://quotes.homeyou.com/?step=1&attributes=..."
}
],
"signupUrl": "https://www.homeyou.com/pro",
"headingName": "Painters",
"heroQuestion": "What type of painting service do you need?",
"heroQuestionTypes": [
{
"display_answer": "Interior Painting",
"url": "https://quotes.homeyou.com/?step=1&attributes=..."
},
{
"display_answer": "Exterior Painting",
"url": "https://quotes.homeyou.com/?step=1&attributes=..."
}
],
"costsWidget": {
"location": "Aurora, CO",
"title": "Average cost for Basement Remodeling",
"minCost": "16,075",
"maxCost": "21,718",
"getPricesUrl": "https://quotes.homeyou.com/?step=1...",
"chartImage": "data:image/png;base64,iVBORw0KGgo...",
"links": [
{
"url": "https://www.homeyou.com/co/aurora/basement-remodeling",
"label": "Basement Remodeling Aurora"
}
...
]
},
"relatedArticles": [
{
"title": "How to Choose the Best Painter for Your Home",
"url": "https://www.homeyou.com/how-to-choose-the-best-painter",
"imageUrl": "https://homeyou.s3.amazonaws.com/media/Painting/choose-painter.jpg",
"date": "March 15, 2024",
"heatLevel": "12,453"
},
{
"title": "Interior vs Exterior Painting: What You Need to Know",
"url": "https://www.homeyou.com/interior-vs-exterior-painting",
"imageUrl": "https://homeyou.s3.amazonaws.com/media/Painting/interior-exterior.jpg",
"date": "January 8, 2024",
"heatLevel": "8,721"
}
]
}
HTTP Request
GET /directory/profiles/<slug>/<state>/<city>
GET /directory/profiles/<slug>/<state>/<city>/<service>
Path params
| Parameter | Description |
|---|---|
| slug | Category slug |
| state | State URL slug (e.g., new-york) |
| city | City slug (e.g., new-york) |
| service | Service slug to filter results (optional) |
Query params
| Parameter | Required | Description |
|---|---|---|
| page | No | 1-based page number (default: 1). Matches the legacy -<page> URL suffix convention. |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Notes
review_starsis the average rating formatted as a string (e.g."4.50"), ornullwhen the contractor has no reviews.review_start_itemsis always an array of 5 booleans indicating filled/empty star icons, based onreview_stars.- Note the difference between the request
pageparam (1-based) and the responsepagination.page(0-based, e.g.0for the first page). To request the next page, sendpage: pagination.page + 2.
Profile
To get the directory profile page data:
<?php
$url = "https://api-costs.homeyou.com/directory/profile/<slug>";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"seoTitle": "ABC Painting Co. - New York Painters - homeyou",
"seoDescription": "Looking for ABC Painting Co. in New York? Read reviews, find costs and get estimates from ABC Painting Co.",
"profile": {
"id_business": 12345,
"slug": "abc-painting-co-new-york-ny",
"company_name": "ABC Painting Co.",
"address_company": "123 Main St",
"city_company": "New York",
"state_company": "NY",
"zip_code_company": "10001",
"formatted_address": "123 Main St, New York, NY 10001",
"coordinates": "40.7128,-74.0060",
"logo_url": "https://homeyou.s3.amazonaws.com/contractors/123/logo.jpg",
"phone": "(212) 555-XXXX",
"hidden_phone": "(212) 555-XXXX",
"tel_phone": "2125551234",
"website_url": "https://www.abcpainting.com",
"website_url_formatted": "www.abcpainting.com",
"website_robots": "follow",
"description": "We are a full-service painting company serving the New York area.",
"category_display": "Painter",
"is_claimed": true,
"is_licensed": true,
"is_insured": true,
"rating": 85,
"review_count": 12,
"review_count_text": "12 Reviews",
"review_stars": "4.50",
"review_start_items": [true, true, true, true, true],
"time_in_business": "10 years",
"claim_url": "https://claim.homeyou.com/claim/12345",
"phone_url": "/abc-painting-co-new-york-ny/phone",
"review_url": "/abc-painting-co-new-york-ny/review",
"quote_url": "https://quotes.homeyou.com/?&step=1&attributes=%7B%22category%22%3A%223%22%7D"
},
"category": {
"nm_category": "Painting",
"cd_category": "3",
"url_slug_category": "painting"
},
"state": {
"nm_state": "New York",
"url_state": "new-york",
"abbreviation_state": "NY"
},
"city": {
"nm_city": "New York",
"slug_city": "new-york",
"prefix_state": "NY"
},
"highlights": [
"House Painting in Brooklyn, NY",
"Interior Painting in Hoboken, NJ",
"Exterior Painting in Queens, NY"
],
"servicesOffered": [
{
"nm_category": "Painting",
"services": [
{
"nm_service": "House Painting",
"service_id": 101,
"service_code": "HOUSE_PAINTING",
"service_slug": "house-painting"
},
{
"nm_service": "Interior Painting",
"service_id": 102,
"service_code": "INTERIOR_PAINTING",
"service_slug": "interior-painting"
}
]
}
],
"licenseInfo": [
{
"label": "Licensed in",
"value": "New York"
},
{
"label": "Number",
"value": "NY-12345"
}
],
"insuranceInfo": [
{
"label": "Company",
"value": "State Farm"
},
{
"label": "Amount",
"value": "$1,000,000"
}
],
"businessHours": [
{
"name": "Monday",
"dayofweek": 1,
"start": "8AM",
"end": "6PM",
"closed": false,
"today": false
},
{
"name": "Today",
"dayofweek": 2,
"start": "8AM",
"end": "6PM",
"closed": false,
"today": true
}
...
],
"socialMedia": [
{
"name": "facebook",
"url": "https://www.facebook.com/abcpainting",
"title": "Facebook"
}
...
],
"options": [
{
"name": "residential",
"value": true,
"label": "Residential"
},
{
"name": "commercial",
"value": false,
"label": "Commercial"
},
{
"name": "financing",
"value": false,
"label": "Offer Financing"
},
{
"name": "emergency",
"value": false,
"label": "Emergency Service"
},
{
"name": "credit-card",
"value": true,
"label": "Accept Credit Card"
}
],
"detailedInfo": [
{
"label": "Year Established",
"value": "2005"
},
{
"label": "Business Categories",
"value": "Painting in New York, NY"
}
],
"reviews": [
{
"id_review": 9876,
"author_review": "John D.",
"text_review": "Great work, highly recommended!",
"rating_review": 5,
"dt_review": "2024-03-15 10:00:00"
}
...
],
"faq": "<p>Frequently asked questions about Painting in New York...</p>",
"relatedServices": [
{
"nm_service": "House Painting",
"service_slug": "house-painting"
},
{
"nm_service": "Deck Staining",
"service_slug": "deck-staining"
}
...
],
"relatedCategories": [
{
"nm_category": "Flooring",
"url_slug_category": "flooring"
},
{
"nm_category": "Drywall",
"url_slug_category": "drywall"
}
...
],
"nearCities": [
{
"nm_city": "Brooklyn",
"prefix_state": "NY",
"slug_city": "brooklyn",
"url_state": "new-york"
},
{
"nm_city": "Jersey City",
"prefix_state": "NJ",
"slug_city": "jersey-city",
"url_state": "new-jersey"
}
...
],
"bannerJobDone": [
{
"title": "When do you need the job done?",
"url": "https://quotes.homeyou.com/?step=1&attributes=..."
},
{
"title": "Within 1 week",
"url": "https://quotes.homeyou.com/?step=1&attributes=..."
},
{
"title": "1 - 2 Weeks",
"url": "https://quotes.homeyou.com/?step=1&attributes=..."
},
{
"title": "More than 2 Weeks",
"url": "https://quotes.homeyou.com/?step=1&attributes=..."
}
],
"signupUrl": "https://www.homeyou.com/pro",
"afterSearching": [
{
"label": "House Painting in Brooklyn NY",
"url_slug_category": "painting",
"url_state": "new-york",
"slug_city": "brooklyn",
"service_slug": "house-painting"
},
{
"label": "Flooring in Queens NY",
"url_slug_category": "flooring",
"url_state": "new-york",
"slug_city": "queens",
"service_slug": "hardwood-floor-installation"
}
...
]
}
HTTP Request
GET /directory/profile/<slug>
Path params
| Parameter | Description |
|---|---|
| slug | Profile slug |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Phone
To get the directory profile phone page data:
<?php
$url = "https://api-costs.homeyou.com/directory/phone/<slug>";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"seoTitle": "ABC Painting Co. - New York Painters - Phone Number",
"nm_company": "ABC Painting Co.",
"phone": "(212) 555-1234",
"tel_phone": "2125551234",
"slug": "abc-painting-co-new-york-ny",
"category": {
"nm_category": "Painting",
"url_slug_category": "painting"
},
"state": {
"nm_state": "New York",
"url_state": "new-york"
},
"city": {
"nm_city": "New York",
"slug_city": "new-york"
}
}
HTTP Request
GET /directory/phone/<slug>
Path params
| Parameter | Description |
|---|---|
| slug | Profile slug |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Review
GET — Review page data
To get the review page data:
<?php
$url = "https://api-costs.homeyou.com/directory/review/<slug>";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"seoTitle": "ABC Painting Co. - New York Painters - Reviews",
"profile": {
"slug": "abc-painting-co-new-york-ny",
"company_name": "ABC Painting Co.",
"logo_url": "https://homeyou.s3.amazonaws.com/contractors/123/logo.jpg",
"address_company": "123 Main St",
"city_company": "New York",
"state_company": "NY",
"zip_code_company": "10001"
},
"category": {
"nm_category": "Painting",
"url_slug_category": "painting"
},
"reviews": [
{
"id_review": 9876,
"first_name": "John",
"rating_review": 5,
"date": "Mar 15, 2024",
"text": "Great work, highly recommended!"
},
{
"id_review": 9875,
"first_name": "Sarah",
"rating_review": 4,
"date": "Jan 08, 2024",
"text": "Very professional and clean."
}
...
]
}
GET /directory/review/<slug>
Path params
| Parameter | Description |
|---|---|
| slug | Profile slug |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
POST — Submit a review
To submit a review:
<?php
$url = "https://api-costs.homeyou.com/directory/review/<slug>";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN',
'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'review_rating' => 5,
'review_text' => 'Excellent work, very professional!',
'author_review' => 'John D.',
]));
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response (success):
{
"success": true
}
Example response (error):
{
"success": false,
"error": "Review text is required"
}
POST /directory/review/<slug>
Path params
| Parameter | Description |
|---|---|
| slug | Profile slug |
Body params
| Parameter | Required | Description |
|---|---|---|
| review_rating | Yes | Rating from 1 to 5 |
| review_text | Yes | Review text |
| id | Yes | Encoded user id |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
| Content-Type | application/json |
Profiles Sitemap
To get the profiles sitemap index:
<?php
$url = "https://api-costs.homeyou.com/directory/sitemap";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response (index — no path params):
{
"level": 0,
"letters": ["A", "B", "C", "..."],
"groups": {
"A": [
{ "url": "a1", "name": "Aaron - Abbot" },
{ "url": "a2", "name": "Abbott - Abram" }
],
"B": [
{ "url": "b1", "name": "Bab - Bake" }
]
}
}
Example response (level 1 —
/directory/sitemap/A):
{
"level": 1,
"l1": "A",
"letters": ["A", "B", "C", "..."],
"groups": [
{ "url": "a1", "name": "Aaron - Abbot" },
{ "url": "a2", "name": "Abbott - Abram" }
]
}
Example response (level 2 —
/directory/sitemap/A/a1):
{
"level": 2,
"l1": "A",
"l2": "a1",
"letters": ["A", "B", "C", "..."],
"groups": [
{ "url": "1", "name": "Aaron - Aar" },
{ "url": "2", "name": "Aaro - Aarb" }
]
}
Example response (level 3 —
/directory/sitemap/A/a1/1):
{
"level": 3,
"l1": "A",
"l2": "a1",
"l3": "1",
"letters": ["A", "B", "C", "..."],
"profiles": [
{ "url": "/aaron-plumbing-new-york-ny", "name": "Aaron Plumbing New York" },
{ "url": "/aarb-electric-boston-ma", "name": "Aarb Electric Boston" }
]
}
HTTP Request
GET /directory/sitemap
GET /directory/sitemap/<l1>
GET /directory/sitemap/<l1>/<l2>
GET /directory/sitemap/<l1>/<l2>/<l3>
Path params
| Parameter | Description |
|---|---|
| l1 | Letter (A–Z or 1–9) |
| l2 | Group 1 key (e.g., a1, a2) |
| l3 | Group 2 key (numeric, e.g., 1, 2) |
Returns 404 if the requested key has no data in Redis.
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
City
This is the city data retrieve service. The endpoints in this area allow us to retrieve city demographic, real estate, weather, and home improvement information.
City Detail
To get city detail page data:
<?php
$url = "https://api-costs.homeyou.com/city/<city>/<state>";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"seoTitle": "Home Service Contractors in Miami, FL",
"seoDescription": "Find the best home service contractors in Miami, FL. Read reviews and research project cost information for home services in Miami.",
"city": "Miami",
"stateCode": "FL",
"slug_city": "miami",
"url_state": "florida",
"pdfUrl": "//www.homeyou.com/city-pdf/miami-fl.pdf",
"ratingImageUrl": "https://www.homeyou.com/images/infographic/homeyou-city-rating-b-plus.png",
"cityGrade": "B+",
"cityRating": 7,
"overallRating": 8,
"overalText": "Miami, FL is a great place to live. It has its pros and cons like any city, but with a quality of life rating of 7/10 and an overall value of 8/10, it's no surprise why so many people choose to live here.",
"population": {
"total": "442,241",
"density": "12,139",
"malePercentage": 49,
"femalePercentage": 51,
"marriedPercentage": 38,
"singlePercentage": 62,
"medianAge": 40,
"densityText": "Compared to New York, Miami has a low population density. Miami is perfect for those who want to be in the city without constantly rubbing shoulders.",
"relativeDensity": [18, 56]
},
"weather": {
"averageTemperature": 77,
"sunny": 72,
"snowFall": 0,
"rainFall": 56
},
"realEstate": {
"medianHomeCost": "348,000",
"medianHomeAge": 42,
"homesOwned": 29.4,
"homesRented": 56.1,
"housingVacant": 14.5,
"homeAppreciationPercentage": 4.2,
"annualPropertyTaxPercent": 0.97
},
"quality": {
"airQuality": 42,
"crimeRate": 45,
"unemploymentRate": 4,
"ourPros": 312,
"averageProRating": "4.20",
"politicalMajorityDemocrat": true,
"democratPercentage": "58.3",
"republicanPercentage": "38.1",
"independentPercentage": "3.6"
},
"jobs": {
"managementPercentage": 14.2,
"salesPercentage": 27.8,
"servicePercentage": 21.5,
"productionPercentage": 8.3,
"constructionPercentage": 7.1
},
"education": {
"highSchoolPercentage": 77,
"graduateDegreePercentage": 9,
"associateDegreePercentage": 7,
"bachelorDegreePercentage": 20,
"pupilTeacherRatio": 17
},
"commute": {
"avgCommuteTime": 29,
"nationalAvgCommuteTime": 26,
"publicTransportationPercentage": 12,
"workAtHomePercentage": 4,
"carpoolPercentage": 11,
"carPercentage": 71
},
"religion": [
{
"label": "Catholic",
"value": 0.32,
"color": "#87BFFF"
},
{
"label": "Protestant",
"value": 0.18,
"color": "#57A5FF"
}
...
],
"referenceCity": {
"city": "New York",
"stateCode": "NY",
"slug_city": "new-york",
"populationDensity": "27,012"
},
"topCities": [
{
"slug_city": "anchorage",
"prefix_state": "AK",
"nm_city": "Anchorage"
},
{
"slug_city": "atlanta",
"prefix_state": "GA",
"nm_city": "Atlanta"
}
...
],
"stateLinks": [
{
"nm_state": "Alabama",
"url_state": "alabama",
"abbreviation_state": "AL"
},
{
"nm_state": "Alaska",
"url_state": "alaska",
"abbreviation_state": "AK"
}
...
],
"costDataLinks": [
{
"nm_service": "AC Companies",
"url_slug": "fl-ac-companies-miami-costs"
},
{
"nm_service": "House Painting",
"url_slug": "fl-house-painting-miami-costs"
}
...
]
}
HTTP Request
GET /city/<city>/<state>
Path params
| Parameter | Description |
|---|---|
| city | City slug (e.g., miami) |
| state | State 2-letter code, lowercase (e.g., fl) |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
City PDF
To get the city info PDF (raw binary, can be used directly as a link or iframe
src):
<?php
$url = "https://api-costs.homeyou.com/city/pdf/miami-fl.pdf";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
Raw application/pdf binary content.
HTTP Request
GET /city/pdf/<slug>
Path params
| Parameter | Description |
|---|---|
| slug | City + state slug with .pdf suffix, e.g. miami-fl.pdf (<slug_city>-<state>.pdf) |
Notes
- This endpoint does not require authentication, the same as the chart image endpoints.
- The response
Content-Typeisapplication/pdfandContent-Dispositionisinline; filename="<slug>.pdf". - The
pdfUrlfield returned by City Detail points to this endpoint when there is no pre-generated/cached PDF for the city.
Emails
This is the email tracking and unsubscribe service. The endpoints in this area back the links and tracking pixels embedded in marketing/transactional emails, as well as the Next.js pages they open.
Email Content
To get the email content to render in the Next.js page:
<?php
$url = "https://api-costs.homeyou.com/emails/<slug>";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"content": "<html>...</html>"
}
Example response (slug not found):
{
"error": "not-found"
}
HTTP Request
GET /emails/<slug>
Path params
| Parameter | Description |
|---|---|
| slug | Email tracking slug from the email link |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Email Open Pixel
Used as the
srcof a tracking<img>inside the email itself, registers an "open" event:
<?php
$url = "https://api-costs.homeyou.com/emails/<slug>/img";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
Raw image/gif 1x1 transparent pixel.
HTTP Request
GET /emails/<slug>/img
Path params
| Parameter | Description |
|---|---|
| slug | Email tracking slug from the email link |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Notes
- Always returns the pixel image, even when the slug is not found, so the open event is logged when the slug is valid and silently ignored otherwise.
Email Link Click Tracking
Used as the
hrefof links inside the email itself. Registers a click event and redirects to the destination URL:
<?php
$url = "https://api-costs.homeyou.com/emails/<slug>/<action>";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
302 Found redirect, with Location header pointing to the tracked destination URL.
HTTP Request
GET /emails/<slug>/<action>
Path params
| Parameter | Description |
|---|---|
| slug | Email tracking slug from the email link |
| action | Click identifier for the link/CTA being tracked (any value other than img, unsubscribe) |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Email Unsubscribe (Pending)
Clicking the "unsubscribe" link in the email opens the Next.js page, which calls this endpoint to load the confirmation step:
<?php
$url = "https://api-costs.homeyou.com/emails/<slug>/unsubscribe";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"status": "pending",
"slug": "abc123"
}
HTTP Request
GET /emails/<slug>/unsubscribe
Path params
| Parameter | Description |
|---|---|
| slug | Email tracking slug from the email link |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Email Unsubscribe (Confirm)
Called when the user confirms the unsubscribe action on the Next.js page:
<?php
$url = "https://api-costs.homeyou.com/emails/<slug>/unsubscribe/confirm";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"success": true
}
HTTP Request
GET /emails/<slug>/unsubscribe/confirm
Path params
| Parameter | Description |
|---|---|
| slug | Email tracking slug from the email link |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Unsubscribe by Token
Programmatic unsubscribe call from the Next.js app, given an unsubscribe token:
<?php
$url = "https://api-costs.homeyou.com/emails/unsubscribe";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
'token' => 'TOKEN',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"success": true
}
Example response (missing/invalid token):
{
"success": false,
"status": "invalid"
}
HTTP Request
POST /emails/unsubscribe
Body params
| Parameter | Required | Description |
|---|---|---|
| token | Yes | Unsubscribe token |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Site
Home
To get the home page data:
<?php
$url = "https://api-costs.homeyou.com/home";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"seoTitle": "homeyou | Get Qualified Help from Nearby Home Improvement Professionals",
"seoDescription": "Find the best home improvement pros near you. Compare reviews, get quotes and hire the right contractor for the job.",
"phoneNumber": "1-844-HOMEYOU",
"telPhoneNumber": "18449663968",
"signupUrl": "https://www.homeyou.com/pro",
"quotesUrl": "https://quotes.homeyou.com/?step=1",
"featuredArticles": {
"topTrendingRows": [
{
"title": "Our Guide to 2015's Hottest Interior Designs",
"url": "https://www.homeyou.com/guide-to-2015-interior-designs",
"imageUrl": "https://homeyou.s3.amazonaws.com/media/Interior Design/design3.jpg",
"heatLevel": "7,731"
}
...
],
"landscapeRows": [ ... ],
"homeImprovementRows": [ ... ]
},
"browseCategories": [
{
"name": "Handyman",
"attributes": "%7B%22category%22%3A%229%22%2C%22service%22%3A%22135%22%7D",
"imageUrl": "https://www.homeyou.com/images/directory/popular/handyman@2x.webp"
},
{
"name": "Painting",
"attributes": "%7B%22category%22%3A%2212%22%2C%22service%22%3A%22271%22%7D",
"imageUrl": "https://www.homeyou.com/images/directory/popular/painting@2x.webp"
}
...
],
"categoriesList": {
"Trending": [
{
"nm_category": "Plumbing",
"url_slug_category": "plumbing",
"imageUrl": "https://www.homeyou.com/images/icons/categories_v2/plumbing.svg"
}
...
],
"Interior": [ ... ],
"Exterior": [ ... ],
"Other Services": [ ... ]
}
}
HTTP Request
GET /home
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Newsletter
To subscribe to the newsletter:
<?php
$url = "https://api-costs.homeyou.com/newsletter";
$data = json_encode([
'email' => 'user@example.com',
]);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"success": true
}
HTTP Request
POST /newsletter
Body params
| Parameter | Required | Description |
|---|---|---|
| Yes | Email address |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Contact
To submit a contact form:
<?php
$url = "https://api-costs.homeyou.com/contact";
$data = json_encode([
'full-name' => 'John Doe',
'email' => 'john@example.com',
'phone' => '5551234567',
'message' => 'Hello, I have a question.',
'cf-turnstile-response' => 'TURNSTILE_TOKEN',
'url' => '',
]);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"success": true
}
HTTP Request
POST /contact
Body params
| Parameter | Required | Description |
|---|---|---|
| full-name | Yes | Full name of the sender |
| Yes | Email address | |
| phone | No | Phone number |
| message | Yes | Message body |
| cf-turnstile-response | Yes | Cloudflare Turnstile token from the widget |
| url | Yes | Honeypot field — must be sent empty |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Subnav
To get the subnav list data:
<?php
$url = "https://api-costs.homeyou.com/subnav?token=TOKEN";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"popularProjects": [
{
"url_slug_category": "plumbing-tasks",
"nm_category": "Plumbing Tasks",
"attributes": "%7B%22category%22%3A%221%22%2C%22service_code%22%3A%22PLUMBING%22%7D"
},
{
"url_slug_category": "handyman-tasks",
"nm_category": "Handyman Tasks",
"attributes": "%7B%22category%22%3A%229%22%2C%22service_code%22%3A%22HANDYMAN%22%7D"
},
...
],
"servicesNearYou": [
{
"slug": "plumbing",
"label": "Plumbing",
"category": "1",
"servicesNearYou": [
{
"id_question": "5",
"display_category": "1",
"cd_category": "1",
"display_answer": "Drain Cleaning",
"service_code": "DRAIN_CLEANING",
"attribute_answer": "",
"criteria_answer": "",
"order_answer": "5",
"attributes_json": "%7B%22category%22%3A%221%22%2C%22service_code%22%3A%22DRAIN_CLEANING%22%7D"
},
{
"id_question": "6",
"display_category": "1",
"cd_category": "1",
"display_answer": "Septic System Repair",
"service_code": "SEPTIC_SEWER_REPAIR",
"attribute_answer": "",
"criteria_answer": "",
"order_answer": "6",
"attributes_json": "%7B%22category%22%3A%221%22%2C%22service_code%22%3A%22SEPTIC_SEWER_REPAIR%22%7D"
},
...
],
"popularServices": [
{
"id_question": "1",
"display_category": "1",
"cd_category": "1",
"display_answer": "Septic System Installation",
"service_code": "SEPTIC_SEWER",
"attribute_answer": "",
"criteria_answer": "",
"order_answer": "1",
"attributes_json": "%7B%22category%22%3A%221%22%2C%22service_code%22%3A%22SEPTIC_SEWER%22%7D"
},
{
"id_question": "2",
"display_category": "1",
"cd_category": "1",
"display_answer": "Septic System Replacement",
"service_code": "SEPTIC_SEWER",
"attribute_answer": "",
"criteria_answer": "",
"order_answer": "2",
"attributes_json": "%7B%22category%22%3A%221%22%2C%22service_code%22%3A%22SEPTIC_SEWER%22%7D"
},
...
]
},
{
"slug": "handyman",
"label": "Handyman",
"category": "9",
"servicesNearYou": [
{
"id_question": "44",
"display_category": "9",
"cd_category": "9",
"display_answer": "Glass Installation or Repair",
"service_code": "GLASS_REPAIR",
"attribute_answer": "",
"criteria_answer": "",
"order_answer": "5",
"attributes_json": "%7B%22category%22%3A%229%22%2C%22service_code%22%3A%22GLASS_REPAIR%22%7D"
},
{
"id_question": "45",
"display_category": "9",
"cd_category": "9",
"display_answer": "Bathroom Repair",
"service_code": "HANDYMAN_BATHROOM",
"attribute_answer": "",
"criteria_answer": "",
"order_answer": "6",
"attributes_json": "%7B%22category%22%3A%229%22%2C%22service_code%22%3A%22HANDYMAN_BATHROOM%22%7D"
},
...
],
"popularServices": [
{
"id_question": "40",
"display_category": "9",
"cd_category": "9",
"display_answer": "Handyman Tasks",
"service_code": "HANDYMAN",
"attribute_answer": "",
"criteria_answer": "",
"order_answer": "1",
"attributes_json": "%7B%22category%22%3A%229%22%2C%22service_code%22%3A%22HANDYMAN%22%7D"
},
{
"id_question": "41",
"display_category": "9",
"cd_category": "9",
"display_answer": "Plumbing Tasks",
"service_code": "HANDYMAN_PLUMBING",
"attribute_answer": "",
"criteria_answer": "",
"order_answer": "2",
"attributes_json": "%7B%22category%22%3A%229%22%2C%22service_code%22%3A%22HANDYMAN_PLUMBING%22%7D"
},
...
]
},
...
]
}
Retrieve information about the currently authenticated user.
HTTP Request
GET /subnav?token=TOKEN
Token url query param
| Parameter | Description |
|---|---|
| token | API token |
Alphabetical Sitemap
To get the site's alphabetical service index:
<?php
$url = "https://api-costs.homeyou.com/sitemap";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response (index — no path params):
{
"level": 0,
"title": "homeyou - Alphabetical Service Index",
"items": [
{ "key": "a", "label": "AC Companies ... Awning Installers" },
{ "key": "b", "label": "Backsplash Installers ... Bricklayers" }
]
}
Example response (
/sitemap/<key>— intermediate level):
{
"level": 1,
"title": "Service Index - AC, Com ... Aw, Ins",
"key": "a",
"up": null,
"prev": null,
"next": "b",
"items": [
{ "key": "aab", "label": "AC Companies ... Air Duct Cleaners", "level": 2 },
{ "key": "aac", "label": "Air Sealing ... Appliance Repair", "level": 2 }
]
}
Example response (
/sitemap/<key>— 3-character key, with nested children):
{
"level": 2,
"title": "Service Index - AC, Com ... Air, Du",
"key": "aab",
"up": null,
"prev": "aaa",
"next": "aac",
"items": [
{
"key": "aaba",
"label": "AC Companies",
"level": 3,
"children": [
{ "label": "AC Companies in New York, NY", "url": "https://www.homeyou.com/ny/new-york/ac-companies" },
{ "label": "AC Companies in Boston, MA", "url": "https://www.homeyou.com/ma/boston/ac-companies" }
]
}
]
}
Example response (
/sitemap/<key>— leaf level, items with directurl):
{
"level": 3,
"title": "Service Index - AC, Com ... AC, Com",
"key": "aaba",
"up": "aab",
"prev": null,
"next": "aabb",
"items": [
{ "label": "AC Companies in New York, NY", "level": 3, "url": "https://www.homeyou.com/ny/new-york/ac-companies" },
{ "label": "AC Companies in Boston, MA", "level": 3, "url": "https://www.homeyou.com/ma/boston/ac-companies" }
]
}
HTTP Request
GET /sitemap
GET /sitemap/<key>
Path params
| Parameter | Description |
|---|---|
| key | Sitemap node key from a previous response's items[].key/next/prev/up |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Notes
- This is the legacy "Alphabetical Service Index" sitemap (
sitemaptable), distinct from the Profiles Sitemap. items[].key(when present) links to another/sitemap/<key>page;items[].url(leaf items,level: 3) links directly to the destination page.up,prev, andnextare sitemap keys for navigation, ornullwhen not applicable.- Returns
400 Bad Requestifkeydoes not exist or has no children.
Gallery
This is the gallery data retrieve service.
Gallery Index
To get the gallery page data for a category:
<?php
$url = "https://api-costs.homeyou.com/gallery/painting";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"seoTitle": "Painting Gallery - homeyou",
"seoDescription": "Browse Painting photos and gallery images on homeyou.",
"category": {
"name": "Painting",
"slug": "painting"
},
"picture": {
"id": 1001,
"full_url": "https://homeyou.s3.amazonaws.com/pictures/painting-room.jpg",
"title": "Beautiful Living Room Paint",
"description": "A stunning living room repainted in modern neutrals.",
"photographer_name": "John Smith",
"photographer_image_url": "https://homeyou.s3.amazonaws.com/photographers/john-smith.jpg",
"photographer_url": "https://www.johnsmithphotos.com"
},
"pictures": [
{
"id": 1002,
"full_url": "https://homeyou.s3.amazonaws.com/pictures/kitchen-paint.jpg",
"title": "Kitchen Cabinet Repaint",
"description": "White shaker cabinets repainted in sage green.",
"photographer_name": "Jane Doe",
"photographer_image_url": "https://homeyou.s3.amazonaws.com/photographers/jane-doe.jpg",
"photographer_url": null
}
...
],
"nextId": 1002,
"prevId": 1010
}
HTTP Request
GET /gallery/<slug>
Path params
| Parameter | Description |
|---|---|
| slug | Category slug |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Gallery Image
To get a single image and related pictures:
<?php
$url = "https://api-costs.homeyou.com/gallery/image/1001";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"seoTitle": "Beautiful Living Room Paint - homeyou",
"seoDescription": "A stunning living room repainted in modern neutrals.",
"category": {
"name": "Painting",
"slug": "painting"
},
"picture": {
"id": 1001,
"full_url": "https://homeyou.s3.amazonaws.com/pictures/painting-room.jpg",
"title": "Beautiful Living Room Paint",
"description": "A stunning living room repainted in modern neutrals.",
"photographer_name": "John Smith",
"photographer_image_url": "https://homeyou.s3.amazonaws.com/photographers/john-smith.jpg",
"photographer_url": "https://www.johnsmithphotos.com"
},
"related": [
{
"id": 1005,
"full_url": "https://homeyou.s3.amazonaws.com/pictures/bedroom-paint.jpg",
"title": "Master Bedroom Accent Wall",
"description": "Deep blue accent wall in master bedroom.",
"photographer_name": null,
"photographer_image_url": null,
"photographer_url": null
}
...
]
}
HTTP Request
GET /gallery/image/<id>
Path params
| Parameter | Description |
|---|---|
| id | Picture ID |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Blogger
This service allows users to submit a guest blogger application.
Submit Blogger Application
To submit a guest blogger application:
<?php
$url = "https://api-costs.homeyou.com/blogger";
$data = json_encode([
'fullname' => 'Jane Doe',
'email' => 'jane@blog.com',
'blog-url' => 'https://janeblog.com',
'blog-name' => "Jane's Blog",
'blog-description' => 'Home improvement tips and tricks.',
'why-interested' => 'I love writing about home decor.',
'facebook' => 'https://facebook.com/janeblog',
'twitter' => 'https://twitter.com/janeblog',
'pinterest' => '',
'instagram' => '',
'favorite-topics' => 'Painting, Landscaping',
]);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"success": true
}
HTTP Request
POST /blogger
Body params
| Parameter | Required | Description |
|---|---|---|
| fullname | Yes | Full name of the applicant |
| Yes | Email address | |
| blog-url | Yes | URL of the applicant's blog |
| blog-name | No | Blog name (defaults to fullname) |
| blog-description | No | Short description of the blog |
| why-interested | No | Why the applicant wants to blog |
| No | Facebook profile URL | |
| No | Twitter profile URL | |
| No | Pinterest profile URL | |
| No | Instagram profile URL | |
| favorite-topics | No | Favorite topics to write about |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Opt-Out
This service allows users to request removal from the homeyou leads list.
Submit Opt-Out
To submit an opt-out request:
<?php
$url = "https://api-costs.homeyou.com/opt-out";
$data = json_encode([
'first-name' => 'John',
'last-name' => 'Doe',
'email' => 'john@example.com',
'phone' => '5551234567',
'company' => '',
'user-agent' => 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
'user-ip' => '127.0.0.1',
]);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"success": true
}
HTTP Request
POST /opt-out
Body params
| Parameter | Required | Description |
|---|---|---|
| first-name | Yes | First name |
| last-name | Yes | Last name |
| Yes | Email address | |
| phone | No | Phone number (digits only, last 10 used) |
| company | Yes | Honeypot field — must be sent empty |
| user-agent | Yes | User agent string |
| user-ip | Yes | User IP address |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Verify Opt-Out Token
To verify an opt-out token (called from email confirmation link):
<?php
$url = "https://api-costs.homeyou.com/opt-out/pending?token=TOKEN";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"success": true
}
HTTP Request
GET /opt-out/pending
Query params
| Parameter | Required | Description |
|---|---|---|
| token | Yes | Verification token received via email |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Leads
This is the leads data retrieve service.
Lead Intel
To post a lead metadata:
<?php
$url = "https://api-costs.homeyou.com/leads/intel";
$data = [
'lead_id' => 1,
'request_id' => 1,
'status' => 'pending',
'data' => [
'images' => [
'https://datahand-image.desenvox.com/datahand/dev/0267e008-e423-4a7f-b96c-60a7e6aa5d2a/staticmap',
],
'address' => '240 MAIN ST, WOBURN, MA',
'latitude' => 42.475204,
'longitude' => -71.15027,
'insights' => [
'Condo • 1108 sqft',
'2 bedrooms • 2.5 bathrooms',
'Built in 2007',
'Estimated price: $574,000',
],
],
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer {YOUR_TOKEN}',
'Content-Type: application/json'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example success response:
{
"success": true
}
Example error response:
{
"success": true,
"error": "Failed to save lead metadata: Lead ID and data are required"
}
Post a lead metadata.
HTTP Request
POST /leads/intel
Request body
| Parameter | Type | Description |
|---|---|---|
| lead_id | integer | Lead ID |
| request_id | string | Request ID |
| status | string | Status |
| data | array | Data |
Lead Info
To get the lead info:
<?php
$url = "https://api-costs.homeyou.com/leads/info/<hashId>";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer {YOUR_TOKEN}'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example success response:
{
"createdAt": 1762188897,
"address": "1st Main Street",
"city": "Woburn",
"state": "MA",
"zipcode": "01801",
"firstName": "Jeser",
"lastName": "Mota",
"email": "jeser@homeyou.com",
"phone": "7777777788",
"propertyType": "Home",
"projectStatus": "Ready to Hire",
"timeframe": "Timing is Flexible",
"ownhome": "Yes",
"description": "Teste",
"cdCategory": "7",
"categorySlug": "additions-and-remodels",
"categoryName": "Additions and Remodels",
"service": null,
"notes": null,
"leadIntel": {
"formattedAddress": "1st Main Street, Woburn, MA • 01801",
"images": [
"https://datahand-image.desenvox.com/datahand/dev/0267e008-e423-4a7f-b96c-60a7e6aa5d2a/staticmap"
],
"latitude": 42.475204,
"longitude": -71.15027,
"insights": [
"Condo • 1108 sqft",
"2 bedrooms • 2.5 bathrooms",
"Built in 2007",
"Estimated price: $574,000"
]
},
"upsells": [
{
"category": "",
"slug": "painting",
"categoryName": "Painting",
"title": "Painting",
"description": "",
"pills": [],
"badge": "",
"ctaText": "",
"imgUrl": "https://placehold.co/600x400",
"campaign": {
"code": "campaign-code",
"token": "campaign-token"
},
"upsell": {
"upsell": true,
"upsell_parent_id": 123,
"upsell_type": "homeyou-dashboard-receipt"
}
},
{
"category": 15,
"slug": "roofing",
"categoryName": "Roofing",
"title": "Roofing",
"description": "",
"pills": [],
"badge": "",
"ctaText": "",
"imgUrl": "https://placehold.co/600x400",
"campaign": {
"code": "campaign-code",
"token": "campaign-token"
},
"upsell": {
"upsell": true,
"upsell_parent_id": 123,
"upsell_type": "homeyou-dashboard-receipt"
}
},
...
]
}
Get a lead info.
HTTP Request
GET /leads/info/<hashId>
Request body
| Parameter | Type | Description |
|---|---|---|
| hashId | string | Hash project |
Affiliates
This is the affiliates data send service. The endpoints in this area allow us to send information about all affiliates data.
Index
To send the affiliates index page data:
<?php
$url = "https://api-costs.homeyou.com/affiliates";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $_POST);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer TOKEN'
]);
$response = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);
echo $response;
?>
Example response:
{
"success": true,
}
HTTP Request
POST /affiliates
Headers:
- Authorization: Bearer TOKEN
Body params (multipart/form-data)
Accepts any field sent via POST. Examples:
| Parameter | Description |
|---|---|
| fullName | Full Name |
| phone | Phone Number |
| Email Address |
Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Automation
These endpoints trigger automation routines for internal operational jobs. Currently, the available routes are focused on Cost Guide content.
Overview
Automation endpoints are used for internal operational jobs. At this moment, the routes below are focused on Cost Guide content.
Common Headers
| Header | Description |
|---|---|
| Authorization | Bearer token (e.g., Bearer TOKEN) |
Notes
- Endpoints in this section are
POST. - Endpoints that accept body params use JSON (
Content-Type: application/json). - Some operations queue background jobs and return execution summary fields.
Import Cost Guide Content
Imports Cost Guide content from the configured Google Spreadsheet URL.
HTTP Request
POST /automation/import-cost-guide-content
Headers:
- Authorization: Bearer TOKEN
- Content-Type: application/json
Body params (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
| format | string | no | Optional import format. |
| force | boolean | no | Forces import behavior when supported by importer. |
Example request:
{
"format": "full",
"force": true
}
Example response:
{
"success": true
}
Generate All Charts
This operation queues chart generation jobs for all Cost Guide content entries.
HTTP Request
POST /automation/generate-all-charts
Headers:
- Authorization: Bearer TOKEN
Example response:
{
"success": true,
"message": "All charts generation started."
}
Generate Charts
This operation queues chart generation jobs for one or more Cost Guide content slugs.
HTTP Request
POST /automation/generate-charts
Headers:
- Authorization: Bearer TOKEN
- Content-Type: application/json
Body params (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
| slugs | array[string] | yes | List of Cost Guide content slugs. |
Example request:
{
"slugs": ["bathroom-remodel-cost", "roof-repair-cost"]
}
Example response:
{
"success": true,
"message": "Charts generation started for the queued slugs.",
"queued_slugs": ["bathroom-remodel-cost"],
"not_found_slugs": ["roof-repair-cost"],
"skipped_no_assets": []
}
Clear Cost Guide Content Cache
This operation clears the Cloudflare cache for specific Cost Guide content slugs.
HTTP Request
POST /automation/clear-cost-guide-content-cache
Headers:
- Authorization: Bearer TOKEN
- Content-Type: application/json
Body params (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
| slugs | array[string] | yes | List of Cost Guide content slugs. |
Example request:
{
"slugs": ["kitchen-remodel-cost", "window-replacement-cost"]
}
Example response:
{
"success": true,
"message": "CF Cache clearing started for the queued URLs.",
"queued_urls": ["https://www.example.com/cost/kitchen-remodel-cost"],
"not_found_slugs": ["window-replacement-cost"]
}
Clear All Cost Guide Content Cache
This operation clears the Cloudflare cache for all Cost Guide content URLs.
HTTP Request
POST /automation/clear-all-cost-guide-content-cache
Headers:
- Authorization: Bearer TOKEN
Example response:
{
"success": true,
"message": "All cost guide content cache cleared."
}