"분명히 styles는 제대로 넣었는데, 왜 기본 지도 그대로지?"

꽤 한참을 헤매다가 원인을 알아냈다.
바로, 결제 계정 미등록 때문이다.

💡 해결의 실마리: StackOverflow에서 찾은 힌트

구글링 중에 StackOverflow에서 한 유저의 답변을 보고 결정적인 힌트를 얻었다:

"Styling is not working unless you have a valid API key." "Google Maps are working without the API key with a dark overlay saying 'For development purposes', so I didn't expect that some feature would be silently ignored."

이 글을 보고 알게 됐다. 지도 자체는 API 키 없이도 어느 정도 작동하지만, styles 같은 일부 고급 기능은 API 키 + 결제 계정이 모두 있어야 작동한다는 사실을!

🧩 문제 상황

import mapStyles from "./mapStyles.json";

<GoogleMap
  // ...
  options={{ styles: mapStyles }}
/>

스타일 JSON을 넣었는데도 전혀 적용되지 않고, 그냥 기본 구글맵 스타일만 나오는 상황. 콘솔 에러도 없고, 코드도 맞는데 뭐가 문제지?

✅ 원인: Google Maps는 결제 계정이 등록되어 있어야 스타일이 적용된다

styles를 직접 넣는 방식이든 mapId를 사용하는 방식이든,
모두 Google Cloud Platform(GCP)에 결제 계정이 등록되어 있어야 작동한다.

Google은 지도를 기본 형태로는 무료로 제공하지만,
커스터마이징(스타일 적용)은 유료 기능에 포함되어 있어서 결제 계정이 필요하다.

🔧 해결 방법

1. Google Cloud Console
2. 좌측 메뉴 > Billing(결제)로 이동
3. 현재 사용 중인 프로젝트에 결제 계정 연결
4. 페이지 새로고침 or 앱 재실행

적용되던 styles JSON이 드디어 반영된다 🎉

찾아보니 개인 프로젝트의 경우는 무료 체험 한도를 넘지 않기 때문에

⚠️ 주의할 점

• GCP에서 Maps JavaScript API가 활성화되어 있는지 확인
• API 키에 리퍼러 제한이 있는 경우, 현재 개발 중인 URL이 허용되어야 함 (localhost, 127.0.0.1:3000 등)
• GCP에서 요구하는 styles JSON 구조를 지켜야한다.
• 결제 계정을 등록해도, 무료 체험 환경을 벗어나지 않는 한 요금이 청구되지 않지만, 막상 결제 정보를 입력하는 건 여전히 부담스럽게 느껴진다..💸

🧪 적용 예시 (정상 작동하는 경우)

import mapStyles from "./mapStyles.json";

<GoogleMap
  // ...
  options={{ styles: mapStyles }} // 결제 계정 등록 시 정상 반영!
/>

아래 스크린샷은 mapStyles.json을 적용한 뒤 실제로 지도의 스타일이 정상 반영된 모습이다. "For development purposes only" 문구도 말끔히 사라졌다.

📌 마무리

구글맵 스타일링이 적용 안 될 때는 일단 결제 계정이 등록되어 있는지 먼저 체크하자.
API 키 설정, 콘솔 에러가 없더라도 스타일이 적용되지 않는다면 100% 결제 계정 때문일 가능성 높음.

프론트엔드 기술 스택은 React + TypeScript이며, 지도 위에 데이터를 시각화하는 간단한 예제를 만들어봤습니다.

🎯 목표

• Google Maps를 React에서 사용하기
• GeoJSON을 기반으로 지도에 행정구역 표시하기
• 각 시도마다 다른 색상 입히기
• 마우스 오버시 스타일 변화 적용하기

📦 사용한 라이브러리

npm install @react-google-maps/api

@react-google-maps/api는 Google Maps를 React에서 쉽게 사용할 수 있도록 도와주는 라이브러리입니다.

🧩 GeoJSON 데이터 준비

GeoJSON은 다음과 같이 생긴 형태로, 각 시도별 경계 정보를 담고 있어요.

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [...]
  },
  "properties": {
    "CTP_KOR_NM": "대구광역시",
    "CTP_ENG_NM": "Daegu"
  }
}

properties.CTP_KOR_NM 속성을 활용해서 색상을 지정합니다.

🧪 구현 코드

// components/KoreaMap.tsx
import { GoogleMap, LoadScript } from "@react-google-maps/api";
import { useRef } from "react";

const containerStyle = {
  width: "100%",
  height: "100vh",
};

const center = {
  lat: 36.5,
  lng: 127.5,
};

const regionColors: Record<string, string> = {
  서울특별시: "#e41a1c",
  부산광역시: "#377eb8",
  대구광역시: "#4daf4a",
  인천광역시: "#984ea3",
  광주광역시: "#ff7f00",
  대전광역시: "#ffff33",
  울산광역시: "#a65628",
  세종특별자치시: "#f781bf",
  경기도: "#999999",
  강원특별자치도: "#66c2a5",
  충청북도: "#fc8d62",
  충청남도: "#8da0cb",
  전라북도: "#e78ac3",
  전라남도: "#a6d854",
  경상북도: "#ffd92f",
  경상남도: "#e5c494",
  제주특별자치도: "#b3b3b3",
};

export default function KoreaMap({ geoJson }: { geoJson: any }) {
  const mapRef = useRef<google.maps.Map | null>(null);

  const onLoad = (map: google.maps.Map) => {
    mapRef.current = map;

    map.data.addGeoJson(geoJson);

    map.data.setStyle((feature) => {
      const name = feature.getProperty("CTP_KOR_NM");
      const fillColor =
        typeof name === "string" && name in regionColors
          ? regionColors[name]
          : "#cccccc";

      return {
        fillColor,
        strokeColor: "#555",
        strokeWeight: 1,
        fillOpacity: 0.6,
      };
    });

    map.data.addListener("mouseover", (event: any) => {
      map.data.overrideStyle(event.feature, { fillColor: "#FEB24C" });
    });

    map.data.addListener("mouseout", () => {
      map.data.revertStyle();
    });
  };

  return (
    <LoadScript googleMapsApiKey={process.env.REACT_APP_GOOGLE_MAPS_API_KEY!}>
      <GoogleMap
        mapContainerStyle={containerStyle}
        center={center}
        zoom={7}
        onLoad={onLoad}
      />
    </LoadScript>
  );
}

참고: .env 파일에 Google Maps API Key를 넣어주고 REACT_APP_GOOGLE_MAPS_API_KEY=... 형식으로 설정해야 합니다.

🤯 타입스크립트 이슈 해결

처음엔 이런 에러가 발생했어요:

TS2538: Type 'unknown' cannot be used as an index type.

이는 feature.getProperty("CTP_KOR_NM")의 반환 타입이 unknown이기 때문이었습니다.
이를 해결하기 위해 typeof name === "string"으로 먼저 체크한 다음,
name in regionColors로 키 존재 여부를 확인해 타입 안정성을 확보했습니다.

if (typeof name === "string" && name in regionColors) {
  const fillColor = regionColors[name]; // 안전!
}

🌈 결과 화면

• 대한민국 시도가 지도에 표시됨
• 각 시도마다 지정한 색상으로 구분됨
• 마우스를 올리면 fillColor가 변경되어 하이라이트 효과

💡 배운 점

• Google Maps API에서 map.data.addGeoJson()으로 GeoJSON을 직접 추가할 수 있다.
• map.data.setStyle()은 Feature별로 스타일을 커스터마이징할 수 있는 유용한 기능!
• value is Type 형태의 타입 가드 함수로 TypeScript에서도 안전한 GeoJSON 핸들링이 가능
• in 연산자는 객체의 키 존재 여부를 안전하게 체크하는 데 꼭 필요함

🧩 다음 목표

• 시도 클릭 시 해당 지역 정보 표시
• 시각화에 animation 효과 추가
• 공공데이터 API와 연동하여 실시간 데이터 반영하기

🙌 마무리

지도 시각화는 생각보다 재미있고, 활용도가 높은 작업이었습니다.
특히 GeoJSON을 어떻게 활용하느냐에 따라, 행정구역 시각화부터 데이터 기반 분석까지 다양한 프로젝트로 확장할 수 있겠다는 가능성을 느꼈어요.

궁금한 점이나 도움이 필요하신 분은 댓글로 남겨주세요! 읽어주셔서 감사합니다 ☺️

"Google 지도를 제대로 로드할 수 없습니다. 이 웹사이트의 소유자이신가요?"

처음에는 "내 코드가 잘못됐나?" 싶었지만, 찾아보니 문제는 API 키가 유효하지 않거나, 결제 계정이 등록되지 않은 경우 발생하는 현상이더라고요.

💳 원인은 바로 결제 계정 미등록!

저의 경우, 무료 크레딧 기간이 이미 만료된 상태였고,
결제 계정을 등록하지 않아서 아래와 같이 지도에 워터마크가 뜨는 상황이었어요.

지도 위에 For development purposes only 문구가 표시되고, 지도가 흐릿하게 출력됩니다.

📌 Google Cloud 요금 정책 정리

처음에는 "결제 등록 = 요금 바로 청구" 라고 생각해서 망설였는데,
Google Cloud의 요금 정책은 생각보다 친절하고 안전하게 설계되어 있더라고요.

✅ 요금 관련 핵심 요약

• 결제 계정을 등록하면 $300의 무료 크레딧이 제공됩니다.
• 크레딧이 소진되거나 유효기간이 끝나도, 사용자가 직접 유료 계정으로 전환하지 않는 한 요금은 청구되지 않습니다.
• 결제 계정을 등록해도, 무료 체험 환경을 벗어나지 않는 한 안전합니다.
  • 구글 무료 체험 환경 정보
  • 구글맵 무료 사용량 정보

😅 그런데도 나는 아직 결제 등록을 못했어요

아무리 안전하다고 해도, 결제 정보를 넣는 건 살짝 부담스럽기도 하죠.
그래서 저도 아직까지는 결제 등록을 하지 않았고,
그 결과 아래처럼 지도가 완전히 출력되지 않고 있습니다.

📷 아래는 실제 내 프로젝트에서의 지도 상태

🔐 그래도 걱정된다면?

요금이 걱정된다면, 최소한 API 키의 보안 설정(리퍼러 제한)은 꼭 해두는 걸 추천드려요.
이렇게 하면 내 API 키가 다른 사이트에 도용되는 걸 방지할 수 있습니다.

👉 Google Maps API 키 보안을 위한 Referrer 제한 설정법

✨ 마무리

결제 계정 등록이 무섭게 느껴질 수 있지만,
Google Cloud는 “내가 원하지 않는 한 요금이 나가지 않게” 잘 설계돼 있었습니다.
저처럼 무료 크레딧 기간이 끝났더라도, 조금 더 정보를 알고 나면
조심스럽게 사용해볼 수 있을 거예요 🙌

✅ 목표

• Google Maps에 대한민국 시도 경계 데이터를 GeoJSON으로 시각화
• 경계 hover 시 색상 변경
• React + TypeScript 기반

📦 사용 기술

• React
• TypeScript
• @react-google-maps/api
• GeoJSON (대한민국 시도 경계 데이터)

1. 패키지 설치

npm install @react-google-maps/api

2. Google Maps API 키 발급

• Google Cloud Platform
• 프로젝트 생성 → Maps JavaScript API 활성화
• API 키 발급 → .env에 저장

REACT_APP_GOOGLE_MAPS_API_KEY=your_api_key_here

⚠️ 꼭 리퍼러 제한 설정하자! (*.yourdomain.com/*) 리퍼러 제한 설정 방법이 궁금하다면 아래 글을 참고해보자! 🔗 구글 Maps API 키 보안을 위한 Referrer 제한 설정법

3. GeoJSON 준비

• 공공데이터포털에서 대한민국 시도 경계 GeoJSON 다운로드
• type: FeatureCollection 형태여야 함
• 나는 이미 다른 분이 잘 정리해둔 GeoJSON 파일을 다운로드해서 사용했다. (정말 감사합니다! 🙏)
• GeoJSON 파일 출처: https://yeomss.tistory.com/267?utm_source=chatgpt.com

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": { "name": "서울특별시" },
      "geometry": {
        "type": "Polygon",
        "coordinates": [...]
      }
    },
    ...
  ]
}

4. 지도 컴포넌트 만들기

// components/KoreaMap.tsx
import { GoogleMap, LoadScript } from '@react-google-maps/api';
import { useRef } from 'react';

const containerStyle = {
  width: '100%',
  height: '100vh',
};

const center = {
  lat: 36.5,
  lng: 127.5,
};

export default function KoreaMap({ geoJson }: { geoJson: any }) {
  const mapRef = useRef<google.maps.Map | null>(null);

  const onLoad = (map: google.maps.Map) => {
    mapRef.current = map;

    // GeoJSON 데이터 추가
    map.data.addGeoJson(geoJson);

    // 기본 스타일 지정
    map.data.setStyle({
      fillColor: '#FFEDA0',
      strokeColor: '#555',
      strokeWeight: 1,
      fillOpacity: 0.6,
    });

    // Hover 스타일
    map.data.addListener('mouseover', (event: any) => {
      map.data.overrideStyle(event.feature, { fillColor: '#FEB24C' });
    });

    map.data.addListener('mouseout', (event: any) => {
      map.data.revertStyle();
    });
  };

  return (
    <LoadScript googleMapsApiKey={process.env.REACT_APP_GOOGLE_MAPS_API_KEY!}>
      <GoogleMap
        mapContainerStyle={containerStyle}
        center={center}
        zoom={7}
        onLoad={onLoad}
      />
    </LoadScript>
  );
}

5. App.tsx에서 사용하기

import KoreaMap from './components/KoreaMap';
import sidoGeoJson from './SIDO_MAP_2022.json'; // GeoJSON import

function App() {
  return <KoreaMap geoJson={sidoGeoJson} />;
}

export default App;

💡 Tip

• GeoJSON 구조가 FeatureCollection이 아니면 mapshaper.org에서 변환 추천
• 도형이 너무 복잡하면 렌더링이 느릴 수 있으니 단순화 작업 고려
• 모바일에선 zoom 조절 필요 (8~9 적당)

✅ 결과

마무리

Google Maps에서 GeoJSON을 쉽게 불러올 수 있다는 점은 정말 편리하다.
GeoJSON만 잘 준비되면 지도 시각화는 생각보다 어렵지 않다.

다음엔 시군구 단위 또는 마우스 클릭 시 정보 보여주기 등 인터랙션을 더해볼 예정! 질문은 댓글로 편하게 남겨주세요 🙌

필요하면 이 포스트에 맞는 이미지나 코드 스니펫용 gist도 같이 넣을 수 있어.
포스팅용으로 꾸며주는 것도 도와줄 수 있으니까, 원하면 알려줘!

하지만! 이 API Key는 기본적으로 아무 웹사이트에서나 사용할 수 있기 때문에
아무런 제한 없이 방치하면 다른 사람이 내 API 키를 마음대로 가져다 쓸 수도 있습니다.
그 결과는? 👉 과금 폭탄 😱

그래서 꼭 필요한 게 바로 리퍼러(Referrer) 제한 설정이에요.

🧠 리퍼러(Referrer) 제한이란?

내 API 키를 사용할 수 있는 웹사이트(출처, 도메인)를 지정하는 보안 설정

즉, “이 키는 오직 내사이트.com에서만 쓸 수 있어!” 라고 구글에 알려주는 보안 설정이에요.

예를 들어 이렇게 설정하면:

✅ 왜 꼭 설정해야 할까?

• 내 API 키가 외부에 유출되더라도, 지정된 도메인이 아니면 사용 불가
• 의도치 않은 API 사용으로 Google Cloud 비용이 폭증하는 걸 방지
• 회사나 팀 프로젝트에서도 기본 보안 습관으로 강력 추천

⚙️ 리퍼러 제한 설정 방법

1. Google Cloud Console 접속
2. API 및 서비스 > 사용자 인증 정보 메뉴 클릭
3. 사용 중인 API 키 선택
4. "애플리케이션 제한사항"에서 👉 웹사이트(HTTP 리퍼러) 선택
5. 허용할 도메인 입력

// 로컬 개발 환경
http://localhost:3000/*

// 배포 환경
https://yourdomain.com/*

// 서브도메인까지 허용할 경우
https://*.yourdomain.com/*

6. 💾 저장 버튼 클릭!

📸 설정 화면 예시

API 키 상세 설정 화면

위처럼 "웹사이트" 항목이 선택되어 있어야 합니다.

🧪 설정 후 확인

• 잘못된 도메인에서 키를 쓰면 콘솔에 아래 오류가 떠요:

  RefererNotAllowedMapError

• 반대로, 설정한 도메인에서는 문제 없이 지도가 잘 뜨면 OK!

✅ 요약

지금 구글 지도 프로젝트를 시작하려고 한다면,
API 키 발급 후 리퍼러 제한부터 꼭 설정해두세요.
작은 습관 하나가 큰 사고를 막아줍니다 🔒

'OpenDota 웹사이트 성능 최적화' 프로젝트의 목적은 크롬 개발자 도구를 사용하여 오픈소스 프로젝트의 성능을 분석하고 개선하는 것이다. 우수한 사용자 경험을 제공하는 웹사이트의 기준으로서, 크롬에서 제시하는 성능 평가 지표¹에서 90점 이상을 달성하는 것을 목표로 설정했다.

분석 대상

분석 대상은 OpenDota이다. Dota 2의 경기 데이터를 다양한 통계, 분석 보고서, 리더보드 등으로 제공하여 사용자들이 자신의 게임 성과를 확인하고 향상시킬 수 있도록 돕는 오픈소스 프로젝트이다.

OpenDota는 모든 페이지의 평균 성능 점수가 30점대로 낮았다. 이는 사용자 경험과 성능 면에서 개선이 필요한 상황을 의미한다. CLS, FCP, TTI, Speed Index, LCP 등의 모든 성능 지표가 모두 개선이 필요한 상태였기 때문에, 다양한 최적화 기법을 실험해볼 수 있는 이상적인 환경이었다. 따라서 OpenDota를 선정하여 성능 최적화의 효과를 분석하고자 한다.

분석 툴

성능 측정 시 다음 툴들을 사용한다.

• Lighthouse
• 성능 통계
• 성능
• cra-bundle-analyzer

실험환경

성능 체크 환경은 다음과 같이 고정한다.

• Throttling Network: fast 3G CPU: 4x slowdown
• 뷰포트 1920x1080

1: https://developer.chrome.com/docs/lighthouse/performance/performance-scoring?utm_source=lighthouse&utm_medium=devtools&hl=ko#color-coding