Back to BlurLoc

AI integration guide

Use this guide when integrating BlurLoc with a coding agent or LLM. Partial prefixes are preferred because they preserve privacy and support more GDPR-conscious integrations. Learn more at blurloc.com.

Raw Markdown

Goal

Integrate the BlurLoc API into the host project with minimal dependencies and privacy-preserving defaults.

API endpoints

Latest lookup: GET https://blurloc.com/lookup/<prefix>
Versioned lookup: GET https://blurloc.com/v1/lookup/<prefix>
Health: GET https://blurloc.com/api/v1/health
OpenAPI: /openapi
LLM descriptor: /llms.txt

Input rules

Preferred input form is a truncated prefix like 44.206.
Explicit wildcard forms like 44.206.x.x are also valid
Full IPv4 input is accepted by default but discouraged
Add strict=1 if the host application must reject exact IPv4 input

Integration requirements

Use GET /lookup/<prefix>
Default to truncated prefixes
Do not add SDK dependencies unless they are already standard in the host project
Reuse the project's existing HTTP client conventions
Parse these stable fields: api_version, query, match_type, country_code, country_name, asn, as_org, is_hosting_provider, is_vpn, network, probability, warning, candidate_count
Only use full=1 if detailed candidate reasoning is needed
Handle non-200 responses cleanly
Add one focused integration test or mocked unit test
Update the local README or developer docs if the project has them

Example request

curl -s "https://blurloc.com/lookup/44.206."

Example response

{
  "api_version": "v1",
  "query": "44.206.",
  "match_type": "exact",
  "country_code": "US",
  "country_name": "United States",
  "asn": 14618,
  "as_org": "AMAZON-AES",
  "is_hosting_provider": false,
  "is_vpn": false,
  "network": "44.206.0.0/16",
  "probability": 1,
  "warning": null,
  "candidate_count": 1
}

Suggested prompt for a coding agent Recommended starter prompt

Integrate the BlurLoc API into this project.

Requirements:
- Use GET https://blurloc.com/lookup/<prefix>
- Default to truncated prefixes like `44.206.`
- Reuse the project's existing HTTP client patterns
- Do not add dependencies unless clearly necessary
- Parse these stable fields:
  api_version, query, match_type, country_code, country_name, asn, as_org,
  is_hosting_provider, is_vpn, network, probability, warning, candidate_count
- Support exact-IP rejection with strict=1 if the calling flow requires it
- Add one focused test
- Update any relevant docs

Success criteria:
- The app can call BlurLoc with a partial prefix
- Response fields are mapped cleanly into local types
- Errors are handled
- Tests pass

# BlurLoc AI Integration Guide

Use this guide when integrating BlurLoc into an application with a coding agent or LLM.

## Goal

Integrate the BlurLoc API into the host project with minimal dependencies and with privacy-preserving defaults.
Partial prefixes are preferred because they preserve privacy and support more GDPR-conscious integrations.
Learn more at https://blurloc.com/

## API endpoints

- Latest lookup route: `GET https://blurloc.com/lookup/<prefix>`
- Versioned lookup route: `GET https://blurloc.com/v1/lookup/<prefix>`
- Health route: `GET https://blurloc.com/api/v1/health`
- OpenAPI: `https://blurloc.com/openapi.json`
- LLM descriptor: `https://blurloc.com/llms.txt`

## Input rules

- Preferred input form is a truncated prefix like `44.206.`
- Explicit wildcard forms like `44.206.x.x` are also valid
- Strict mode is ON by default. Exact IPv4 input is rejected with 400.
- Pass `strict=0` only if the host application explicitly requires full IP acceptance (compatibility mode)

## Integration requirements

- Use `GET /lookup/<prefix>`
- Default to truncated prefixes
- Do not add SDK dependencies unless they are already standard in the host project
- Reuse the project's existing HTTP client conventions
- Parse the stable top-level response fields:
  - `api_version`
  - `query`
  - `match_type`
  - `country_code`
  - `country_name`
  - `asn`
  - `as_org`
  - `is_hosting_provider`
  - `is_vpn`
  - `network`
  - `probability`
  - `warning`
  - `candidate_count`
- Only use `full=1` if detailed candidate reasoning is needed
- Handle non-200 responses cleanly
- Add one focused integration test or mocked unit test
- Update the local README or developer docs if the project has them

## Example request

```bash
curl -s "https://blurloc.com/lookup/44.206."
```

## Example response

```json
{
  "api_version": "v1",
  "query": "44.206.",
  "match_type": "exact",
  "country_code": "US",
  "country_name": "United States",
  "asn": 14618,
  "as_org": "AMAZON-AES",
  "is_hosting_provider": false,
  "is_vpn": false,
  "network": "44.206.0.0/16",
  "probability": 1,
  "warning": null,
  "candidate_count": 1
}
```

## Suggested prompt for a coding agent

```text
Integrate the BlurLoc API into this project.

Requirements:
- Use GET https://blurloc.com/lookup/<prefix>
- Default to truncated prefixes like `44.206.`
- Reuse the project's existing HTTP client patterns
- Do not add dependencies unless clearly necessary
- Parse these stable fields:
  api_version, query, match_type, country_code, country_name, asn, as_org,
  is_hosting_provider, is_vpn, network, probability, warning, candidate_count
- Do not pass strict=0 unless the calling flow explicitly requires full IP acceptance
- Add one focused test
- Update any relevant docs

Success criteria:
- The app can call BlurLoc with a partial prefix
- Response fields are mapped cleanly into local types
- Errors are handled
- Tests pass
```