Common questions and issues
Answers about cell lookups, location accuracy, API keys, downloads and contributions.
Find answers to common OpenCellID questions below. Choose a section from the page contents, or expand a question to read its answer. Each question has a link you can copy and share.
Finding cells
No. OpenCellID cannot look up a phone number or IMEI, contact a device, or retrieve its current location. We look up estimated cell positions using network identifiers observed by a device: MCC, MNC, LAC/TAC and cell ID. A cell lookup does not reveal a phone's exact position.
See your first API request and our community answer about phone numbers and IMEIs.
You need the cell's MCC, MNC, LAC/TAC and full cell ID, together with its radio technology when known. A cell ID alone, or LAC and cell ID without the network codes, is not enough to identify a cell globally.
On Android, an app such as Tower Collector can show the observed cell information. Keep the identifiers from the same observation and subscription. Convert hexadecimal readings to decimal before sending them to the API; do not split an unfamiliar combined identifier by guessing its digit boundaries.
See the glossary and lookup parameters.
Check MCC, MNC, LAC/TAC, the full cell ID and radio technology. Common mistakes include mixing SIM and serving-network identifiers, using readings from different SIM slots, or confusing hexadecimal and decimal values.
We may not have observations for that cell yet. Operators can also change identifiers, and new contributions take time to process. A missing record does not mean the cell does not exist or the area has no mobile service. See coverage and missing cells.
Read the response body even when HTTP status is 200: a lookup can return error code 1, Cell not found. See API errors.
Use the MCC and MNC reported for the observed cell, alongside that cell's area code, cell ID and radio technology. Your SIM provider's brand or home-network codes may differ from the network currently serving the device. Do not substitute an MNC based only on the provider's name.
See MVNOs and roaming for details.
Use radio=LTE for 4G or radio=NR for 5G NR with the identifiers required by Get cell position. For LTE, pass the TAC as lac and the full cell identity as cellid. An eNB ID identifies a base station and is not a substitute for the full cell ID. PCI is a separate field and is not a globally unique cell identifier.
In dataset downloads, filter the radio column and use area and cell for the area code and cell ID. The unit column holds PCI for LTE or PSC for UMTS. Radio support does not guarantee that we have observations for your cell; coverage varies.
Locations and data meaning
The coordinates are estimated cell positions calculated from contributed observations. They are not surveyed mast coordinates or a device's live GPS position. Estimates can differ from the physical antenna site, especially where observations are sparse or concentrated along a road.
One physical site can serve several cells, sectors and radio technologies. Several rows at nearby or identical coordinates can therefore be valid. Do not count rows as physical towers or remove records solely because their coordinates match.
See coverage and cell counts and our community explanation of cells and towers.
range describes the approximation around the estimated cell position, in meters. It is not an area in square meters, a guaranteed boundary containing the antenna, or a distance within which a phone will reliably receive service.
Use it as context for the location estimate. OpenCellID does not provide an operator's measured signal-coverage map. See the database format and our community clarification of range.
No. samples counts contributed measurements assigned to a cell. It does not count calls, subscribers, connected devices or traffic, and it is not a daily activity total. A high count can reflect where contributors collect data; it does not establish how busy the network is.
See the column reference and our community answer about samples.
For GSM, UMTS, LTE and NR records, use the MCC and MNC together and cross-reference a current MCC/MNC allocation list. In downloads, the MNC is named net; for CDMA, net instead represents the SID.
The network identifier does not tell you who owns the physical mast or which retail brand a roaming or MVNO customer uses. See the database format and MVNO guidance.
API keys and requests
Register for an OpenCellID account, then sign in to the dashboard and reveal your key under API Access Tokens. Copy the complete value and keep it private.
Use your key for API requests, dataset downloads and contributions. Follow your first API request to try a lookup.
Copy the complete key from your OpenCellID account and check for missing characters or extra whitespace. For /cell/get, send the key as key, with mcc, mnc, lac and cellid, using the documented request format. The Unwired Labs JSON format with token and a cells array is not the OpenCellID request format.
Cell lookups report an unknown key with code 2 and HTTP 401. Measurement endpoints can return Err: Invalid token or Invalid API key; these responses have different meanings and formats. Check the error reference before retrying.
If a previously working request keeps failing, contact us with its endpoint, error and UTC timestamp. Replace the key with YOUR_API_KEY before sharing a request or response: some error messages echo it. See our community answer about request formats.
Each user receives 1,000 API request credits per day, shared across their API keys. A daily-limit error uses code 7 and HTTP 429. Avoid immediate repeated retries after reaching the limit.
Contributors receive a higher allowance; contact us to arrange additional credits. Commercial plans are also available. For bulk analysis, use dataset downloads. See access and limits.
/cell/getInArea returns at most 50 cells per request. Use limit and offset for pagination, and count cells in the area to check the total. Results can shift between requests as data is updated.
The maximum bounding-box area is 4,000,000 square meters (4 km²). Check that BBOX uses latmin,lonmin,latmax,lonmax. For a city, region or country, download the dataset and filter by coordinates instead of making a large area request. Telephone dialing area codes are not LAC/TAC values.
See List cells in an area and downloads.
Downloads and CSV files
Open the download page, enter your OpenCellID API token and choose a country file or the full dataset. Use the smallest file that covers your work. Daily change files are also available.
Exports are generated daily by 02:00 GMT. See Download the dataset and full exports and daily changes.
You can download each file twice per day. Once you reach the limit, wait until the next day instead of repeatedly restarting the download. Keep a local copy for repeated analysis.
For an invalid-token error, check that you entered your own complete API token on the download page. If a file repeatedly fails or appears empty, contact us with its filename, error and UTC timestamp. Remove tokens from any download URLs you share. See access and limits.
Downloads include cells observed in the last 18 months. The API also provides access to older data, so the two can return different results. An export is also a daily snapshot, rather than an immediately updated copy of every lookup result.
Check the export date and match the complete identifiers, including radio technology. See download coverage and our community answer about older cells.
Decompress .gz files before importing them. Large exports can exceed a spreadsheet's row limit; use a CSV processing tool, script or database to read the full file.
The database format reference lists the column order, types and units. For cell lookups, export fields net, area and cell correspond to API fields mnc, lac and cellid. Match them together with mcc and radio, rather than matching cell alone. The export places lon before lat; check the coordinate order your mapping tool expects.
Measurement-upload CSV files use a different schema. Do not submit a downloaded cell export directly as a measurement file.
created and updated are Unix timestamps in seconds, not milliseconds. They describe when a cell was added to our database and when it was last seen and updated. They do not establish when an operator built, activated or retired a tower.
changeable is deprecated and always 1; averageSignal is deprecated and always 0. Do not interpret these fields as a surveyed-location flag or a current signal-strength measurement. See the database format.
Individual measurements are not available for download. The standard downloads contain computed cell records, and daily change files are not a complete historical archive. The API can return older cells, but a lookup does not reconstruct the dataset as it existed on a past date.
For historical snapshot requirements, contact us with the dates, area and fields you need so we can discuss availability. See full exports and daily changes.
Contributing and uploads
Collect fresh observations with Tower Collector, or submit observations from your own devices through our measurement API. Include the device's measured location and the cell identifiers observed there. Do not replace the device's GPS coordinates with a guessed tower position.
Observations from different locations can help improve an estimate. If you have a reliable operator or research dataset, contact us to discuss including it. See our community answer about adding cells.
Send the file as the multipart field datafile and your API key as key. Check the exact field names, required values and format in CSV upload, JSON upload or CLF upload. Files must not exceed 4,000,000 bytes.
Read the response body: some failures use HTTP 200. Successful file uploads return 0,OK, including JSON uploads. A message such as No file sent. or Invalid file format. indicates an upload problem. See measurement submission errors.
An accepted upload does not guarantee an immediate change to cell positions. Some measurements may be filtered by validation.
See Processing time. If the issue persists, contact us with the upload time in UTC, format, response and a small redacted example.
Use your own OpenCellID API key in Tower Collector so uploads can be attributed to your account. In the dashboard, look for Analytics → Data Contribution; API request usage is separate from contribution statistics.
If the section is missing, sign out and sign back in. If it is still missing or the figures do not reflect your uploads, contact us with your registered email and upload timestamps. Do not post your API key publicly. See our community update on contribution reports.
More questions
Ask the community or contact us. For a technical issue, include what you expected, the endpoint or filename, the error response and when it happened. Replace API keys with YOUR_API_KEY in examples, URLs and screenshots.